Vibe Math MCP

A high-performance Model Context Protocol (MCP) server for math-ing whilst vibing with LLMs. Built with Polars, Pandas, NumPy, SciPy, and SymPy for optimal calculation speed and comprehensive mathematical capabilities from basic arithmetic to advanced calculus and linear algebra.

Features

21 Mathematical Tools across 6 domains + batch orchestration:

• Basic Calculations (4 tools): Expression evaluation, percentages, rounding, unit conversion
• Array Operations (4 tools): Element-wise operations, statistics, aggregations, transformations
• Statistics (3 tools): Descriptive statistics, pivot tables, correlations
• Financial Mathematics (3 tools): Time value of money, compound interest, perpetuity
• Linear Algebra (3 tools): Matrix operations, system solving, decompositions
• Calculus (3 tools): Derivatives, integrals, limits & series
• Batch Execution (1 tool): Multi-tool orchestration for complex workflows

Installation

IDEs

Claude Desktop

Open Settings > Developer > Edit Config and add:

For published package:

{
  "mcpServers": {
    "Math": {
      "command": "uvx",
      "args": ["vibe-math-mcp"]
    }
  }
}

For local development:

{
  "mcpServers": {
    "Math": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/vibe-math-mcp",
        "run",
        "vibe-math-mcp"
      ]
    }
  }
}

Claude Code

Quick setup (CLI):

Published package:

claude mcp add --transport stdio math -- uvx vibe-math-mcp

Local development:

claude mcp add --transport stdio math -- uvx --from /absolute/path/to/vibe-math-mcp vibe-math-mcp

Team setup (create .mcp.json in project root for shared use with Claude Code and/or IDEs)

{
  "mcpServers": {
    "math": {
      "command": "uvx",
      "args": ["vibe-math-mcp"]
    }
  }
}

Verify: Run claude mcp list or use /mcp or view available servers in IDEs.

Try it

• "Calculate 15% of 250" → uses percentage
• "Find determinant of [[1,2],[3,4]]" → uses matrix_operations
• "Integrate x^2 from 0 to 1" → uses integral
• "If I invest $1000 at 5% annual interest compounded monthly for 10 years, what will be the future value?" → uses compound_interest
• If I was paid the square root of $69m in 10 years, what's the present value at 7% discount rate? → uses batch_execute (calculate -> financial_calcs)

Output Control

All tools automatically support output control for maximum flexibility and token efficiency. The LLM can specify the desired verbosity.

Control response verbosity using the output_mode parameter (available on every tool):

Batch Execution

For multi-step workflows, batch_execute chains multiple calculations in a single request—achieving 90-95% token reduction. Reference prior outputs using $operation_id.result syntax, and the engine automatically handles dependency resolution and parallel execution for speed.

Perfect for: Bond pricing, financial models, statistical pipelines, complex transformations

Complete Tool Reference

Note: All tool parameters include detailed descriptions with concrete examples directly in the MCP interface. Each parameter shows expected format, use cases, and sample values to make usage obvious without referring to external documentation.

Basic Calculations

Array Operations

Statistics

Financial Mathematics

Linear Algebra

Calculus

---

## Development

### Running Tests

Install dependencies

uv sync

Run all tests

uv run poe test

### Local Development Modes

**STDIO Mode** (default - for Claude Desktop, IDEs):

uv run vibe-math-mcp

**HTTP Mode** (for container testing):

uv run python -m vibe_math_mcp.http_server

## License

MIT License. See `LICENSE` file for details.

## Contributing

Contributions welcome via PRs! Please ensure:

1. Tests pass, and new ones are added if applicable
2. Code is linted & formatted
3. Type hints are included
4. Clear, actionable error messages are provided

## Support

For issues and questions, please open an issue on GitHub.