Skip to main content
Glama
chrishayuk

MCP Math Server

by chrishayuk
OverviewInspectSchemaRelated ServersScoreDiscussions
Python
Hybrid

🧮 Chuk MCP Math Server

PyPI version Python 3.11+ Tests Coverage License: MIT Powered by chuk-mcp-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:

Domain

Functions

Examples

Arithmetic & Number Theory

(420)

Basic operations, primes, sequences, divisibility

add

,

multiply

,

modulo

,

is_prime

,

fibonacci

,

gcd

Trigonometry

(71)

Trig functions, hyperbolic, conversions

sin

,

cos

,

tan

,

sinh

,

radians_to_degrees

Linear Algebra

(33)

Vector and matrix operations

dot_product

,

cross_product

,

matrix_multiply

Statistics

(15)

Descriptive statistics

mean

,

median

,

std_dev

,

variance

Calculus

(9)

Derivatives, integration, root finding

derivative

,

integrate

,

newton_raphson

Geometry

(12)

Shapes, distances, intersections

circle_area

,

distance

,

triangle_area

Probability

(10)

Distribution functions

normal_pdf

,

binomial_pmf

Other

(17)

Advanced operations, sequences, constants, conversions

factorial

,

combinations

,

pi_digits

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 MIT License - see the LICENSE file for details.

🙏 Acknowledgments

🔗 Links

Made with ❤️ by the Chuk MCP Team

High-performance mathematical computation for the Model Context Protocol ecosystem

One-click Deploy
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/chrishayuk/chuk-mcp-math-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server