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):

Mode	Description	Token Savings	Use Case
full	Complete response with all metadata (default)	0% (baseline)	Debugging, full context needed
compact	Remove null fields, minimize whitespace	~20-30%	Moderate reduction, preserve structure
minimal	Primary value(s) only, strip metadata	~60-70%	Fast extraction, minimal context
value	Normalized {value: X} structure	~70-80%	Consistent chaining, maximum simplicity
final	For sequential chains, return only terminal result	~95%	Simple calculations, predictable extraction

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

Tool	Description
calculate	Evaluate mathematical expressions with variable substitution
percentage	Percentage calculations (of, increase, decrease, change)
round	Advanced rounding (round, floor, ceil, trunc)
convert_units	Unit conversions (degrees � radians)

Array Operations

Tool	Description
array_operations	Element-wise operations (add, subtract, multiply, divide, power)
array_statistics	Statistical measures (mean, median, std, min, max, sum)
array_aggregate	Aggregations (sumproduct, weighted average, dot product)
array_transform	Transformations (normalise, standardise, scale, log)

Statistics

Tool	Description
statistics	Comprehensive analysis (describe, quartiles, outliers)
pivot_table	Create pivot tables with aggregation
correlation	Correlation matrices (Pearson, Spearman)

Financial Mathematics

Tool	Description
financial_calcs	Time value of money (PV, FV, PMT, IRR, NPV)
compound_interest	Compound interest with various frequencies

Linear Algebra

Tool	Description
matrix_operations	Matrix operations (multiply, inverse, transpose, determinant, trace)
solve_linear_system	Solve Ax = b systems
matrix_decomposition	Decompositions (eigen, SVD, QR, Cholesky, LU)

Calculus

Tool	Description
derivative	Symbolic and numerical differentiation
integral	Symbolic and numerical integration
limits_series	Limits and series expansions

---

## Development

### Running Tests

```bash
# 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.