Mathematical MCP Server

A small, secure Model Context Protocol (MCP) server that exposes 6 basic mathematical tools to any MCP-compatible AI client (e.g., Claude Desktop, Cursor, VS Code).

Built using Python, FastMCP, Pydantic, and SymPy, this server performs basic arithmetic and safe symbolic expression evaluation.

---

Features

• Standardized Structured Responses: Returns structured JSON responses containing success, result (properly serialized to JSON-friendly types), error, and execution_time_ms.
• Input Validation: Enforces strict type checking using Pydantic.
• Safe Expression Evaluation: Parses and evaluates string equations (e.g., (5+7)*9/3) using a secure whitelist-based SymPy AST walker.
• Robust Error Handling: Intercepts and formats errors like division-by-zero and complex roots.
• Strict I/O Logging: Automatically logs incoming requests, runtime arguments, execution speeds, and errors strictly to stderr to preserve stdout for MCP JSON-RPC protocol transport.

---

Folder Structure

Calculator_MCP_Server/
├── config.py                 # Computational boundaries and whitelists
├── schemas.py                # Pydantic response models
├── utils.py                  # Logging configurations and tool execution wrappers
├── calculator.py             # Pure mathematical algorithms
├── tools.py                  # MCP tools definitions and binding using FastMCP
├── server.py                 # Application entry point
├── requirements.txt          # Python dependencies
├── pyproject.toml            # Formatter (black/ruff) and pytest config
├── .gitignore                # Git files pattern exclusions
└── tests/
    ├── test_calculator.py    # Unit tests for core algorithms
    └── test_tools.py         # Integration tests for tool wrappers

---

Installation & Setup

1. Prerequisites

• Python 3.12+
• pip (Python package installer)

2. Set Up Virtual Environment

Clone this repository and navigate into the folder:

cd Calculator_MCP_Server

Create a virtual environment:

# On Windows
python -m venv .venv
.venv\Scripts\activate

# On macOS/Linux
python3 -m venv .venv
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

---

Running the MCP Server

The server communicates via standard I/O (stdio) by default, making it ideal for local LLM integrations.

# Run server
python server.py

To run with live reloading and access the MCP Inspector web interface (ideal for testing tools in the browser):

fastmcp dev server.py

---

Connecting to MCP Clients

Claude Desktop

To integrate this mathematical server with Claude Desktop, add it to your configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following to the mcpServers object:

{
  "mcpServers": {
    "math-server": {
      "command": "python",
      "args": [
        "c:/Users/Admin/OneDrive/Documents/Projects/Calculator_MCP_Server/server.py"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "MAX_FACTORIAL_N": "10000"
      }
    }
  }
}

Note: Make sure to specify the absolute path to your Python executable if it's not globally available in your environment's PATH.

---

Available Tools

• add(a, b): Returns $a + b$.
• subtract(a, b): Returns $a - b$.
• multiply(a, b): Returns $a \times b$.
• divide(a, b): Returns $a / b$ (raises division-by-zero errors).
• power(base, exponent): Returns $base^{exponent}$ (handles negative bases/exponent calculations).
• evaluate_expression(expression): Safely parses and evaluates mathematical expression strings (e.g. (5+7)*9/3). Supports basic math operators and trigonometric/root functions.

---

Example AI Prompts

You can write naturally to any MCP client equipped with this server:

• "What is 567 × 897?" (calls multiply)
• "What is 2 raised to the power of 10?" (calls power)
• "Calculate (12 + 8) * 3 / 2" (calls evaluate_expression)
• "What is sin(0) + cos(0)?" (calls evaluate_expression)

---

Testing

To run the automated tests:

pytest

To run with coverage or verbose mode:

pytest -v

---

Future Improvements

1. Caching Layer: Cache expensive symbolic evaluations and factorial queries.
2. Extended Solvers: Implement solvers for cubic equations and system of linear equations (using SymPy's linsolve).
3. Advanced Matrix Algorithms: Eigenvalue and eigenvector calculations using NumPy/SciPy.
4. Calculus Tools: Symbolic derivative and integration tools.

---

License

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