Math MCP Learning Server

Educational MCP server demonstrating persistent workspace patterns and mathematical operations. Built with FastMCP 2.0 and the official Model Context Protocol Python SDK.

Available on:

• Official MCP Registry - io.github.clouatre-labs/math-mcp-learning-server
• PyPI - math-mcp-learning-server
• FastMCP Cloud - No installation required

Requirements

Requires an MCP client:

• Claude Desktop - Anthropic's desktop app
• Claude Code - Command-line MCP client
• Goose - Open-source AI agent framework
• OpenCode - Open-source MCP client by SST
• Kiro - AWS's AI assistant
• Gemini CLI - Google's command-line tool
• Any MCP-compatible client

Quick Start

Cloud (No Installation)

Connect your MCP client to the hosted server:

Claude Desktop (claude_desktop_config.json):

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

Local Installation

Automatic with uvx (recommended):

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

Manual installation:

# Basic installation
uv pip install math-mcp-learning-server

# With matrix operations support
uv pip install math-mcp-learning-server[scientific]

# With visualization support
uv pip install math-mcp-learning-server[plotting]

# All features
uv pip install math-mcp-learning-server[scientific,plotting]

Features

• Cross-Session Persistence: Variables survive server restarts and session changes
• Safe Expression Evaluation: Secure mathematical expression parsing with security logging
• Statistical Analysis: Mean, median, mode, standard deviation, variance
• Financial Calculations: Compound interest with formatted output
• Unit Conversions: Length, weight, temperature
• Function Plotting: Base64-encoded PNG plots (matplotlib)
• Statistical Histograms: Distribution visualization with indicators
• Type Safety: Full Pydantic validation for all inputs
• Comprehensive Testing: Complete coverage with security validation
• Cross-Platform Storage: Windows, macOS, Linux support

MCP Implementation

Primitives:

• Tools: 17 tools for mathematical operations, persistence, visualization, and matrix operations
• Resources: 1 resource (math://workspace) for viewing persistent workspace
• Prompts: 2 prompts (math_tutor, formula_explainer) for educational interactions

Transports:

• stdio - Standard input/output for local clients
• HTTP/SSE - Server-Sent Events for cloud/web clients

Workspace persists 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
• plot_line_chart: Create line charts for sequential data visualization
• plot_scatter_chart: Create scatter plots for relationship analysis
• plot_box_plot: Create box plots for statistical distribution comparison
• plot_financial_line: Create financial trend plots with bullish/bearish/volatile patterns

Matrix Operations (requires [scientific] extra)

• matrix_multiply: Multiply two matrices with dimension validation
• matrix_transpose: Transpose a matrix (swap rows and columns)
• matrix_determinant: Calculate determinant of square matrices
• matrix_inverse: Compute matrix inverse with singular matrix detection
• matrix_eigenvalues: Calculate eigenvalues (supports complex numbers)

Note: Matrix operations require NumPy. Install with uv pip install math-mcp-learning-server[scientific]

See Usage Examples for detailed examples of each tool.

Available Prompts

Educational Prompts

• math_tutor: Generate structured tutoring prompts for mathematical concepts (configurable difficulty level)
• formula_explainer: Generate comprehensive formula explanation prompts with step-by-step breakdowns

See Usage Examples for detailed examples of each prompt.

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

# Clone and setup
git clone https://github.com/clouatre-labs/math-mcp-learning-server.git
cd math-mcp-learning-server
uv sync --extra dev --extra plotting

# Test server locally
uv run fastmcp dev src/math_mcp/server.py

Testing

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src --cov-report=html --cov-report=term

# Run specific test category
uv run pytest tests/test_matrix_operations.py -v

Test Suite: 126 tests across 5 categories (HTTP, Math, Matrix, Persistence, Visualization) Coverage: See detailed testing documentation

Code Quality

# Linting
uv run ruff check

# Formatting
uv run ruff format --check

# Security checks
uv run ruff check --select S

Contributing

See CONTRIBUTING.md for guidelines on submitting changes.

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
• Roadmap: Planned features 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

Contributing

We welcome contributions! See CONTRIBUTING.md for development workflow, code standards, and testing procedures.

For maintainers: See MAINTAINER_GUIDE.md for release procedures.

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.