math-mcp-learning-server by clouatre - MCP Server

Math MCP Learning Server

Cloud hosted: Connect any MCP client to https://math-mcp-learning.fastmcp.app/mcp (MCP client required, no local server install needed)

A persistent quantitative workspace built as a Model Context Protocol (MCP) server. This project demonstrates enterprise-grade patterns for MCP development, featuring cross-session state persistence - a unique capability that most LLMs cannot achieve natively.

Perfect for learning MCP fundamentals, demonstrating professional patterns, and serving as a foundation for advanced mathematical workflows.

Built with FastMCP 2.0 and the official Model Context Protocol Python SDK.

Requirements

This is an MCP server - it requires an MCP client to use. Supported clients include:

Claude Desktop - Anthropic's desktop app with native MCP support
Claude Code - Command-line MCP client from Anthropic
OpenCode - Open-source MCP client
Amazon Q - AWS's AI assistant with MCP support
Codex CLI - GitHub Codex command-line interface
Gemini CLI - Google's Gemini command-line tool
Any other MCP-compatible client

Cannot run standalone - The server must be connected through an MCP client.

Quick Start

Option 1: Try it Now (Cloud)

Connect your MCP client to the hosted server - no local installation required!

Claude Desktop:

{
  "mcpServers": {
    "math-cloud": {
      "transport": "http",
      "url": "https://math-mcp-learning.fastmcp.app/mcp"
    }
  }
}

Claude Code:

claude mcp add math-cloud https://math-mcp-learning.fastmcp.app/mcp

Option 2: Run Locally

Choose one of two installation methods:

Method A: Automatic with uvx (recommended)

Configure your MCP client to use uvx - no manual installation needed:

Claude Desktop:

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

Claude Code:

claude mcp add math uvx math-mcp-learning-server

Method B: Manual installation

Install the package:

uv pip install math-mcp-learning-server

Configure your MCP client:

Claude Desktop:

{
  "mcpServers": {
    "math": {
      "command": "math-mcp-learning-server"
    }
  }
}

Claude Code:

claude mcp add math math-mcp-learning-server

Features

Persistent Workspace

Cross-Session State: Save calculations and access them across different MCP client sessions
Persistent Storage: Variables survive server restarts and session changes
Cross-Platform: Works on Windows (%LOCALAPPDATA%), macOS, and Linux (~/.math-mcp)
Thread-Safe: Concurrent access with atomic file operations

Mathematical Operations

Safe Expression Evaluation: Securely evaluate mathematical expressions with enhanced error handling
Statistical Analysis: Calculate mean, median, mode, standard deviation, and variance
Financial Calculations: Compound interest calculations with formatted output
Unit Conversions: Length, weight, and temperature conversions

Visual Learning

Function Plotting: Generate mathematical function plots with base64-encoded PNG output
Statistical Histograms: Visualize data distributions with mean and median indicators
Cloud Deployment: Visualization tools (matplotlib) are included in the cloud deployment
Local Usage: Install with uv pip install math-mcp-learning-server[plotting] for local usage with plotting features

Enterprise-Grade Quality

Security Logging: Monitor and log potentially dangerous expression attempts
Type Safety: Full Pydantic validation for inputs and structured content responses
Comprehensive Testing: Complete test coverage with security and edge case validation
Zero Core Dependencies: Core persistence features use only Python stdlib

MCP Architecture

This server implements the following MCP primitives:

Tools: 8 tools for mathematical operations, persistence, and visualization
Resources: 1 resource (math://workspace) for viewing the persistent workspace
Prompts: 0 (future enhancement opportunity)

Transport Support

This server implements all official MCP transport modes per the MCP specification:

stdio - Standard input/output for local clients (Claude Desktop, Claude Code)
HTTP/SSE - Streamable HTTP with Server-Sent Events for cloud/web clients

Transport-agnostic workspace: Your saved calculations persist across all transport modes and sessions.

Available Tools

Persistent Workspace Tools

save_calculation: Save calculations to persistent storage for cross-session access
load_variable: Access previously saved calculations from any MCP client session

Mathematical Tools

calculate: Safely evaluate mathematical expressions (supports basic ops and math functions)
statistics: Perform statistical calculations (mean, median, mode, std_dev, variance)
compound_interest: Calculate compound interest for investments
convert_units: Convert between units (length, weight, temperature)

Visualization Tools

plot_function: Generate mathematical function plots (base64-encoded PNG)
create_histogram: Create statistical histograms with distribution analysis

See Usage Examples for detailed examples of each tool.

Available Resources

`math://workspace`

View your complete persistent workspace with all saved calculations, metadata, and statistics.

Returns:

All saved variables with expressions and results
Educational metadata (difficulty, topic)
Workspace statistics (total calculations, session count)
Timestamps for tracking calculation history

Development

Project Structure

math-mcp-learning-server/
├── src/math_mcp/
│   ├── server.py          # Main MCP server implementation
│   └── persistence/       # Persistent workspace functionality
├── tests/
│   ├── test_math_operations.py
│   └── test_persistence.py
├── docs/
│   ├── CLOUD_DEPLOYMENT.md
│   └── EXAMPLES.md
├── pyproject.toml
└── README.md

Development Setup

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

# Install dependencies (includes plotting support)
uv sync --extra dev --extra plotting

# Run tests
uv run pytest tests/ -v

# Run type checking
uv run mypy src/

# Run linting
uv run ruff check

# Test the MCP server with FastMCP dev mode
uv run fastmcp dev src/math_mcp/server.py
# Then connect via MCP client (Claude Desktop, Claude Code, etc.)

Adding New Tools

Define input/output models with Pydantic
Add @mcp.tool() decorated function in src/math_mcp/server.py
Implement tool logic with proper validation
Add corresponding tests in tests/

See CONTRIBUTING.md for detailed guidelines.

Documentation

Cloud Deployment Guide: FastMCP Cloud deployment instructions and configuration
Usage Examples: Practical examples for all tools and resources
Contributing Guidelines: Development workflow, code standards, and testing procedures
Future Improvements: Roadmap and enhancement opportunities
Code of Conduct: Community guidelines and expectations

Security

Safe Expression Evaluation

The calculate tool uses restricted eval() with:

Whitelist of allowed characters and functions
Restricted global scope (only math module and abs)
No access to dangerous built-ins or imports
Security logging for potentially dangerous attempts

MCP Security Best Practices

Input Validation: All tool inputs validated with Pydantic models
Error Handling: Structured errors without exposing sensitive information
Least Privilege: File operations restricted to designated workspace directory
Type Safety: Complete type hints and validation for all operations

Publishing

This package is published to PyPI via GitHub Actions workflow. The workflow is triggered on:

New releases (tags matching v*)
Manual workflow dispatch

Publishing workflow:

Create and push a version tag: git tag v0.6.7 && git push origin v0.6.7
GitHub Actions automatically builds and publishes to PyPI
Release notes are generated from commit messages

The package follows semantic versioning and includes comprehensive metadata for discoverability on PyPI.

Contributing

We welcome contributions! This project follows a fast and minimal philosophy while maintaining educational value and professional standards.

Quick Start for Contributors:

Fork the repository
Set up development environment: uv sync --extra dev --extra plotting
Create feature branch: git checkout -b feature/your-feature
Make changes and add tests
Run quality checks: uv run pytest && uv run mypy src/ && uv run ruff check
Submit a pull request

See CONTRIBUTING.md for detailed guidelines including:

Development workflow and Git practices
Code standards and security requirements
Testing procedures and quality assurance
Architecture guidelines and best practices

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to hugues+mcp-coc@linux.com.

License

MIT License - Full license details available in the LICENSE file.