MCP Math Server

🧮 Chuk MCP Math Server

A highly configurable Mathematical Computation Protocol (MCP) server that provides comprehensive mathematical functions with flexible transport options and streaming capabilities.

✨ Features

🔢 Mathematical Capabilities

286 Mathematical Functions across multiple domains
Number Theory: Prime testing, factorization, GCD, LCM, sequences
Arithmetic: Basic operations, advanced calculations, statistics
Real-time Computation: Async processing with timeout support
Function Filtering: Configurable whitelisting/blacklisting by domain or category

🚀 Transport & Streaming

Dual Transport: STDIO and HTTP support
HTTP Streaming: Server-Sent Events for intensive computations
WebSocket Ready: Extensible for real-time applications
CORS Support: Cross-origin requests enabled

⚙️ 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 capabilities

🛡️ Production Ready

Health Monitoring: Built-in health check endpoints
Error Handling: Graceful failure management
Logging: Configurable log levels and output
Rate Limiting: Optional request throttling
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 (MCP Standard)

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

# Or with Python
python src/chuk_mcp_math_server/math_server.py

HTTP Transport

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

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

Example Client Usage

Test with Examples

# Test STDIO client
uv run examples/stdio_client_example.py

# Test HTTP client with streaming
uv run examples/http_client_example.py

Basic HTTP API Usage

# Check server status
curl http://localhost:8000/

# Health check
curl http://localhost:8000/health

# Sample response:
# {
#   "server": "chuk-mcp-math-server",
#   "version": "0.1.0",
#   "functions_available": 286,
#   "transport": "http"
# }

📖 Documentation

Available Functions

The server provides 286 mathematical functions across these domains:

Domain	Functions	Examples
Arithmetic	Basic operations, statistics	`add`, `multiply`, `mean`, `variance`
Number Theory	Primes, factorization, sequences	`is_prime`, `next_prime`, `fibonacci`, `gcd`
Advanced Math	Complex calculations	`sqrt`, `power`, `factorial`, `combinations`

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 number_theory --functions is_prime add

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

# 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"
enable_cors: true
log_level: "INFO"

# Function filtering
domain_whitelist: ["arithmetic", "number_theory"]
function_blacklist: ["slow_function"]

# 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

Environment Variables

export MCP_MATH_TRANSPORT="http"
export MCP_MATH_PORT=8000
export MCP_MATH_LOG_LEVEL="DEBUG"
export MCP_MATH_DOMAIN_WHITELIST="arithmetic,number_theory"

chuk-mcp-math-server

MCP Protocol Usage

Initialize Connection

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "clientInfo": {
      "name": "my-math-client",
      "version": "1.0.0"
    }
  }
}

List Available Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Call Mathematical Function

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "is_prime",
    "arguments": {
      "n": 97
    }
  }
}

🛠️ Development

Project Structure

chuk-mcp-math-server/
├── src/chuk_mcp_math_server/
│   ├── __init__.py              # Package initialization
│   ├── _version.py              # Dynamic version management
│   ├── _cli.py                  # CLI utilities
│   └── math_server.py           # Main server implementation
├── examples/
│   ├── stdio_client_example.py  # STDIO client demo
│   └── http_client_example.py   # HTTP client demo
├── tests/                       # Test suite
├── pyproject.toml              # Project configuration
└── README.md                   # This file

Development Setup

# Install development dependencies
uv sync --group dev

# Install with all optional features
pip install -e .[full]

# Run formatting
black src/ examples/
isort src/ examples/

# Run tests
pytest

# Version information
chuk-mcp-math-server-info

Adding New Functions

Add mathematical functions to the chuk-mcp-math library
Functions are automatically discovered and registered
Use function filtering to control exposure

Custom Configuration

from chuk_mcp_math_server import ServerConfig, ConfigurableMCPMathServer

# Create custom configuration
config = ServerConfig(
    transport="http",
    port=9000,
    domain_whitelist=["arithmetic"],
    enable_cors=True,
    log_level="DEBUG"
)

# Start server
server = ConfigurableMCPMathServer(config)
await server.run()

🌐 HTTP API Reference

Endpoints

Endpoint	Method	Description
`/`	GET	Server status and information
`/health`	GET	Health check and function count
`/mcp`	POST	MCP protocol messages

HTTP Streaming

The server supports Server-Sent Events (SSE) for computationally intensive operations:

// Request with streaming
fetch('/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'fibonacci',
      arguments: { n: 1000 }
    }
  })
})

📊 Performance

Benchmarks

Function Calls: ~1000 ops/sec (simple arithmetic)
Prime Testing: ~100 ops/sec (medium-sized numbers)
Memory Usage: ~50MB baseline + computation overhead
Startup Time: ~2 seconds (286 functions loaded)

Optimization Tips

Use cache_strategy: "smart" for repeated calculations
Increase max_concurrent_calls for high-throughput scenarios
Use function filtering to reduce memory footprint
Enable HTTP streaming for long-running computations

🔧 Troubleshooting

Common Issues

Server Won't Start

# Check dependencies
chuk-mcp-math-server-info

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

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

Function Not Available

# List all functions
chuk-mcp-math-server --domains arithmetic --show-config

# Check filtering
chuk-mcp-math-server --functions is_prime add --show-config

HTTP Connection Issues

# Test server health
curl http://localhost:8000/health

# Check CORS settings
chuk-mcp-math-server --transport http --enable-cors

Debug Information

# Get detailed system info
chuk-mcp-math-server-info --info

# Check version detection
python -c "import chuk_mcp_math_server; chuk_mcp_math_server.print_version_info()"

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Add tests
Run the test suite
Submit a pull request

Code Style

Use black for code formatting
Use isort for import sorting
Follow PEP 8 guidelines
Add type hints where appropriate

📋 Requirements

Core Dependencies

Python 3.11+
chuk-mcp >= 0.5
chuk-mcp-math >= 0.1.0
fastapi >= 0.116.1
uvicorn >= 0.35.0
httpx >= 0.28.1
pyyaml >= 6.0.2

Optional Dependencies

Development tools: pytest, black, isort, mypy
All optional: pip install chuk-mcp-math-server[full]

📝 License

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

🙏 Acknowledgments

Built on the Model Context Protocol (MCP)
Mathematical functions provided by chuk-mcp-math
Inspired by the need for accessible mathematical computation services

🔗 Links

Documentation: GitHub Wiki
Issues: GitHub Issues
MCP Protocol: Official MCP Docs
Mathematical Functions: chuk-mcp-math

Made with ❤️ by the Chuk MCP Team

Bringing mathematical computation to the Model Context Protocol ecosystem

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A Mathematical Computation Protocol server providing 286 mathematical functions across multiple domains with flexible transport options (STDIO/HTTP) and streaming capabilities.

Related MCP Servers

MCP Calculate Server
611711Dark
A
security
A
license
A
quality
A mathematical computation service that enables users to perform symbolic calculations including basic arithmetic, algebra, calculus, equation solving, and matrix operations through the MCP protocol.
Last updated -
1
4
Python
MIT License
MCP Calculator Server
RMahshie
-
security
F
license
-
quality
A calculator server that exposes mathematical functions as tools (add, subtract, multiply, divide, square, power, square root), enabling language models to perform calculations through Model Context Protocol (MCP).
Last updated -
Basic Math MCP Server
bahfahh
A
security
F
license
A
quality
A simple server that provides basic mathematical operations (sum and subtraction) through the Model Context Protocol.
Last updated -
2
1
JavaScript
Learn_MCP Math Server
naveenkumarr1812
-
security
F
license
-
quality
A Model Context Protocol (MCP) server that demonstrates mathematical capabilities through a LangChain integration, allowing clients to perform math operations via the MCP protocol.
Last updated -
Python

View all related MCP servers