🧮 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
• 393 Mathematical Functions available
• Zero-config startup - works out of the box

✨ Features

🔢 Mathematical Capabilities

• 393 Mathematical Functions across multiple domains
• Number Theory: Prime testing, factorization, GCD, LCM, sequences (71 functions)
• Arithmetic: Basic operations, advanced calculations, statistics (322 functions)
• Trigonometry: Comprehensive trigonometric operations (71 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

Installation

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

# Install dependencies
uv sync
# or
pip install -e .

Basic Usage

STDIO Transport (Claude Desktop)

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

# Starts immediately with all 393 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):

{
  "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 393 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

# Install development dependencies
uv sync --group dev

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

# Run tests with coverage
make test-cov

# Run type checking
make typecheck

# Format code
make format

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

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

📊 Performance

Benchmarks

• Peak Throughput: 36,000+ requests/second
• Average Latency: <3ms per tool call
• Startup Time: ~2 seconds (393 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}'

🤝 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 (393 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 MIT License - 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: GitHub | Docs
• chuk-mcp-math: GitHub
• MCP Protocol: Official Specification
• Issues: GitHub Issues

---

Made with ❤️ by the Chuk MCP Team

High-performance mathematical computation for the Model Context Protocol ecosystem