🧮 Chuk MCP Math Server

A highly configurable Mathematical Computation Protocol (MCP) server that provides comprehensive mathematical functions with flexible transport options. Built on the high-performance chuk-mcp-server framework.

⚡ Performance

• 36,000+ RPS peak throughput (inherited from chuk-mcp-server)

• Sub-3ms latency per tool call

• 642 Mathematical Functions available

• Zero-config startup - works out of the box

Related MCP server: MCP Calculator Server

✨ Features

🔢 Mathematical Capabilities

• 642 Mathematical Functions across multiple domains

• Number Theory: Prime testing, factorization, GCD, LCM, sequences (328 functions)

• Arithmetic: Basic operations, advanced calculations (44 functions)

• Trigonometry: Comprehensive trigonometric operations (71 functions)

• Linear Algebra: Vector and matrix operations (33 functions)

• Statistics: Descriptive and inferential statistics (15 functions)

• Calculus: Derivatives, integration, root finding (9 functions)

• Geometry: Shapes, distances, intersections (12 functions)

• Probability: Distribution functions (10 functions)

• Advanced Operations: Complex mathematical operations (22 functions)

• Sequences: Mathematical sequences (12 functions)

• Constants: Mathematical constants (25 functions)

• Conversions: Unit and type conversions (7 functions)

• Real-time Computation: Async processing with proper error handling

• Function Filtering: Configurable allowlists and denylists by domain, category, or function

🚀 Transport & Architecture

• Dual Transport: STDIO (Claude Desktop) and HTTP support

• High Performance: Built on chuk-mcp-server framework

• Auto-detection: Automatically selects optimal transport mode

• Production Ready: 36,000+ RPS, <3ms latency

• Type Safe: Automatic schema generation from Python type hints

⚙️ Configuration

• CLI Configuration: Comprehensive command-line options

• File Configuration: YAML and JSON config file support

• Environment Variables: Container-friendly configuration

• Dynamic Filtering: Runtime function filtering with allowlists and denylists

• Granular Control: Filter by function, domain, or category

🛡️ Production Features

• Zero Configuration: Works out of the box with sensible defaults

• High Test Coverage: 97% code coverage with 114 comprehensive tests

• Type Safe: 100% type-checked with mypy, fully Pydantic-native

• Error Handling: Graceful failure management

• Logging: Configurable log levels and output

• MCP Resources: Built-in resources for function discovery and stats

• Timeout Management: Configurable computation timeouts

🚀 Quick Start

💡 Try it now! Use our free public server at https://math.chukai.io/mcp - no installation required! See Public Server section below.

Installation

Using uvx (Recommended - No Installation Required!)

The easiest way to use the server is with uvx, which runs it without installing:

uvx chuk-mcp-math-server

This automatically downloads and runs the latest version. Perfect for Claude Desktop!

Using uv (Recommended for Development)

# Install from PyPI
uv pip install chuk-mcp-math-server

# Or clone and install from source
git clone https://github.com/chuk-mcp/chuk-mcp-math-server.git
cd chuk-mcp-math-server
uv sync

Using pip (Traditional)

pip install chuk-mcp-math-server

Basic Usage

STDIO Transport (Claude Desktop)

# Start server with STDIO transport (default)
uv run chuk-mcp-math-server

# Starts immediately with all 642 functions available

HTTP Transport (Web APIs)

# Start HTTP server
uv run chuk-mcp-math-server --transport http --port 8000

# Server will be available at http://localhost:8000

Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Use the Public Server (Easiest)

Connect to the hosted public server:

{
  "mcpServers": {
    "math": {
      "command": "uvx",
      "args": [
        "chuk-mcp-client",
        "https://math.chukai.io/mcp"
      ]
    }
  }
}

This requires no local installation and is always up-to-date!

Option 2: Run Locally with uvx

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

Option 3: Run Locally with Local Installation

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

Important: Use absolute paths, not relative or ~ paths.

Restart Claude Desktop and ask: "Can you check if 97 is prime?" - Claude will use the math server!

Example HTTP API Usage

# Test the server
curl http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call a mathematical function
curl http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "is_prime",
      "arguments": {"n": 97}
    }
  }'

📖 Documentation

Available Functions

The server provides 642 mathematical functions across these domains:

Function Filtering

Control which functions are exposed:

# Only expose specific functions
chuk-mcp-math-server --functions add subtract multiply divide

# Expose only arithmetic domain
chuk-mcp-math-server --domains arithmetic

# Exclude specific functions
chuk-mcp-math-server --exclude-functions slow_function

# Combine filters
chuk-mcp-math-server --domains arithmetic number_theory --categories core primes

Configuration Options

Command Line

# Basic configuration
chuk-mcp-math-server --transport http --port 8080 --host 0.0.0.0

# Function filtering
chuk-mcp-math-server --domains arithmetic --functions is_prime add

# Performance tuning
chuk-mcp-math-server --cache-strategy smart --timeout 60

# Logging
chuk-mcp-math-server --verbose  # Debug logging
chuk-mcp-math-server --quiet    # Minimal logging

Configuration File

# config.yaml
transport: "http"
port: 8000
host: "0.0.0.0"
log_level: "INFO"

# Function filtering (allowlist: only these are enabled, denylist: these are excluded)
domain_allowlist: ["arithmetic", "number_theory"]
function_allowlist: ["is_prime", "fibonacci", "add", "multiply"]
function_denylist: ["deprecated_function"]  # Exclude specific functions

# Performance
cache_strategy: "smart"
cache_size: 1000
computation_timeout: 30.0
max_concurrent_calls: 10

# Use configuration file
chuk-mcp-math-server --config config.yaml

# Save current config
chuk-mcp-math-server --domains arithmetic --save-config my-config.yaml

# Show current config
chuk-mcp-math-server --show-config

MCP Resources

The server provides built-in resources for introspection:

# List available functions (via MCP resource)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "math://available-functions"
  }
}

# Get function statistics
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "math://function-stats"
  }
}

# Get server configuration
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "math://server-config"
  }
}

🛠️ Development

Project Structure

chuk-mcp-math-server/
├── src/chuk_mcp_math_server/
│   ├── __init__.py              # Package initialization
│   ├── cli.py                   # CLI implementation
│   ├── config.py                # Base configuration (Pydantic)
│   ├── math_config.py           # Math-specific configuration
│   ├── function_filter.py       # Function filtering logic
│   └── math_server.py           # Main server (uses chuk-mcp-server)
├── tests/                       # Test suite (97% coverage, 114 tests)
├── pyproject.toml              # Project configuration
└── README.md                   # This file

Development Setup

# Clone the repository
git clone https://github.com/chuk-mcp/chuk-mcp-math-server.git
cd chuk-mcp-math-server

# Install development dependencies
uv sync

# Install in editable mode
uv pip install -e ".[dev]"

Running Tests

# Run tests
make test

# Run tests with coverage
make test-cov

# Run specific test file
uv run pytest tests/test_config.py -v

Code Quality

# Run all quality checks (lint, typecheck, security, tests)
make check

# Format code
make format

# Run linting
make lint

# Run type checking
make typecheck

# Run security checks
make security

Building

# Build distribution packages
make build

# This creates wheel and source distributions in dist/

Running Locally

# Run with verbose logging
uv run chuk-mcp-math-server --verbose

# Run HTTP server
make run-http

# Run STDIO server (default)
make run

Custom Server

from chuk_mcp_math_server import create_math_server

# Create server with custom configuration
server = create_math_server(
    transport="http",
    port=9000,
    domain_allowlist=["arithmetic"],  # Only arithmetic functions
    function_denylist=["deprecated_func"],  # Exclude specific functions
    log_level="DEBUG"
)

# Run the server
server.run()

🚀 Deployment

Docker

Build and run with Docker:

# Build the Docker image
make docker-build

# Run the container
make docker-run

# Or manually:
docker build -t chuk-mcp-math-server .
docker run -p 8000:8000 chuk-mcp-math-server

The server will be available at http://localhost:8000.

Fly.io

Deploy to Fly.io for a public server:

# Install flyctl if you haven't already
curl -L https://fly.io/install.sh | sh

# Login to Fly.io
flyctl auth login

# Deploy (first time)
flyctl launch

# Or deploy updates
flyctl deploy

# Check status
flyctl status

# View logs
flyctl logs

The fly.toml configuration is already set up for HTTP mode on port 8000. The server will auto-scale based on traffic (min 0, auto-start/stop).

Environment Variables

Configure via Fly.io secrets:

# Set environment variables
flyctl secrets set MCP_SERVER_LOG_LEVEL=INFO
flyctl secrets set MCP_MATH_CACHE_STRATEGY=smart

# View secrets
flyctl secrets list

GitHub Actions

The repository includes automated workflows:

• Test: Runs on all PRs and commits (Ubuntu, Windows, macOS)

• Release: Creates GitHub releases when tags are pushed

• Publish: Publishes to PyPI automatically on releases

• Fly Deploy: Auto-deploys to Fly.io on main branch pushes

To create a release:

# Bump version in pyproject.toml
make bump-patch  # or bump-minor, bump-major

# Commit the version change
git add pyproject.toml uv.lock
git commit -m "Bump version to 0.2.1"
git push

# Create and push a tag to trigger release
make publish

This will automatically:

1. Create a GitHub release with changelog

2. Run tests on all platforms

3. Build and publish to PyPI

4. Deploy to Fly.io (if configured)

📊 Performance

Benchmarks

• Peak Throughput: 36,000+ requests/second

• Average Latency: <3ms per tool call

• Startup Time: ~2 seconds (642 functions loaded)

• Memory Usage: ~50MB baseline

• Success Rate: 100% under load testing

Performance comes from:

• chuk-mcp-server framework: High-performance MCP implementation

• Async operations: Non-blocking I/O for all function calls

• Type safety: Automatic schema validation with zero overhead

• Optimized registry: Fast function lookup and execution

Optimization Tips

• Use function filtering to reduce memory footprint

• Enable caching for repeated calculations (--cache-strategy smart)

• Use HTTP transport for web APIs, STDIO for local/Claude Desktop

• Adjust --max-concurrent-calls for high-throughput scenarios

🔧 Troubleshooting

Common Issues

Server Won't Start

# Verify installation
python -c "import chuk_mcp_math_server; print(chuk_mcp_math_server.__version__)"

# Verify configuration
chuk-mcp-math-server --show-config

# Debug mode
chuk-mcp-math-server --verbose

Functions Not Loading

# Check if chuk-mcp-math is installed
python -c "import chuk_mcp_math; print(chuk_mcp_math.__version__)"

# Verify function count
chuk-mcp-math-server --show-config | grep total_filtered

Claude Desktop Not Showing Tools

1. Use absolute paths in claude_desktop_config.json (not ~ or relative)

2. Test manually: echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | uv run chuk-mcp-math-server

3. Restart Claude Desktop after config changes

4. Check Claude Desktop logs (Help → Show Logs)

HTTP Connection Issues

# Test server health
curl http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

🌐 Public Server

A free public math server is available at https://math.chukai.io/mcp for anyone to use!

Features

• ✅ Always Available: Hosted on Fly.io with auto-scaling

• ✅ Always Up-to-Date: Automatically deploys from main branch

• ✅ All 642 Functions: Full mathematical function library

• ✅ No Installation Required: Just add to Claude Desktop config

• ✅ Free to Use: No authentication or API keys needed

Quick Start

Add this to your Claude Desktop config:

{
  "mcpServers": {
    "math": {
      "command": "uvx",
      "args": [
        "chuk-mcp-client",
        "https://math.chukai.io/mcp"
      ]
    }
  }
}

Then restart Claude Desktop and ask: "Can you check if 97 is prime?"

Testing the Public Server

The server requires session management for MCP over HTTP. Use chuk-mcp-client to connect:

# Install the client
uvx chuk-mcp-client https://math.chukai.io/mcp

# Or test with curl (requires session ID from chuk-mcp-server)
curl https://math.chukai.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Note: The server uses chuk-mcp-server's session-based HTTP transport, which requires the chuk-mcp-client for proper session management.

Privacy & Usage

• No logging of tool calls or personal data

• No rate limiting (fair use applies)

• Automatically scales based on demand

• Source code is open and auditable

Self-Hosting

Want to host your own? See the Deployment section above for Docker and Fly.io instructions.

🤝 Contributing

We welcome contributions! Here's how to help:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Make your changes

4. Add tests if applicable

5. Ensure tests pass (pytest)

6. Submit a pull request

Code Style

• Follow PEP 8 guidelines

• Maintain 100% type safety with mypy and Pydantic

• Add type hints where appropriate

• Update documentation for new features

• Keep the README up to date

• Aim for high test coverage (currently 97%)

📋 Requirements

Core Dependencies

• Python 3.11+

• chuk-mcp-server >= 0.6 (provides high-performance MCP framework)

• chuk-mcp-math >= 0.1.0 (provides mathematical functions)

• pyyaml >= 6.0.2 (for YAML configuration)

What's Included via chuk-mcp-server

• High-performance HTTP/STDIO transport

• Automatic type inference and validation

• Built-in logging and error handling

• Zero-config startup capability

• Production-grade performance (36K+ RPS)

Optional Dependencies

• Development tools: pytest, pytest-asyncio

• All optional: pip install -e .[dev]

🏗️ Architecture

Built on chuk-mcp-server framework:

• chuk-mcp-server: High-performance MCP server framework (36K+ RPS)

• chuk-mcp-math: Mathematical function library (642 functions)

• This server: Bridges the two with filtering and configuration

The refactored architecture is simpler and more performant:

• Removed custom base server implementation

• Uses chuk-mcp-server's decorator-based API

• Maintains all filtering and configuration features

• Gains automatic performance optimization

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Built on chuk-mcp-server - High-performance MCP framework

• Mathematical functions from chuk-mcp-math

• Follows the Model Context Protocol specification

🔗 Links

• chuk-mcp-server: High-performance MCP framework

• chuk-mcp-math: GitHub

• MCP Protocol: Official Specification

• Issues: GitHub Issues

High-performance mathematical computation for the Model Context Protocol ecosystem