# Directory Structure
```
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
├── requirements.txt
├── server.py
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/.python-version:
--------------------------------------------------------------------------------
```
3.13
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info
# Virtual environments
.venv
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
[](https://mseep.ai/app/colesmcintosh-numpy-mcp)
# NumPy MCP Server
<div align="center">
<strong>A Model Context Protocol (MCP) server for numerical computations with NumPy</strong>
[![MIT licensed][mit-badge]][mit-url]
</div>
[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
[mit-url]: ./LICENSE
[python-badge]: https://img.shields.io/badge/python-3.8%2B-blue.svg
[python-url]: https://www.python.org/downloads/
A Model Context Protocol (MCP) server that provides mathematical calculations and operations using NumPy. This server exposes various mathematical tools through a standardized MCP interface, making it easy to perform numerical computations directly through Claude or other MCP-compatible LLMs.
## Features
- Basic arithmetic operations (addition)
- Linear algebra computations (matrix multiplication, eigendecomposition)
- Statistical analysis (mean, median, standard deviation, min, max)
- Polynomial fitting
## Installation
### Quick Setup with Claude Desktop
The fastest way to get started is to install this server directly in Claude Desktop:
```bash
# Install the server in Claude Desktop
mcp install server.py --name "NumPy Calculator"
```
### Manual Installation
This project uses UV for dependency management. To install:
```bash
# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone the repository
git clone https://github.com/yourusername/math-mcp.git
cd math-mcp
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate # On Unix/macOS
# or
# .venv\Scripts\activate # On Windows
uv pip install -r requirements.txt
```
## Usage
### Development Testing
Test the server locally with the MCP Inspector:
```bash
mcp dev server.py
```
### Claude Desktop Integration
1. Install the server in Claude Desktop:
```bash
mcp install server.py --name "NumPy Calculator"
```
2. The server will now be available in Claude Desktop under "NumPy Calculator"
3. You can use it by asking Claude to perform mathematical operations, for example:
- "Calculate the eigenvalues of matrix [[1, 2], [3, 4]]"
- "Find the mean and standard deviation of [1, 2, 3, 4, 5]"
- "Multiply matrices [[1, 0], [0, 1]] and [[2, 3], [4, 5]]"
### Direct Execution
For advanced usage or custom deployments:
```bash
python server.py
# or
mcp run server.py
```
## Available Functions
The server provides the following mathematical functions through the MCP interface:
### Basic Arithmetic
- `add(a: int, b: int) -> int`: Add two integers together
### Linear Algebra
- `matrix_multiply(matrix_a: List[List[float]], matrix_b: List[List[float]]) -> List[List[float]]`: Multiply two matrices
- `eigen_decomposition(matrix: List[List[float]]) -> Tuple[List[float], List[List[float]]]`: Compute eigenvalues and eigenvectors of a square matrix
### Statistics
- `statistical_analysis(data: List[float]) -> dict[str, float]`: Calculate basic statistics for a dataset including:
- Mean
- Median
- Standard deviation
- Minimum value
- Maximum value
### Data Analysis
- `polynomial_fit(x: List[float], y: List[float], degree: int = 2) -> List[float]`: Fit a polynomial of specified degree to the given data points
## Development
### Project Structure
```
math-mcp/
├── requirements.txt
├── README.md
└── server.py
```
### Code Quality
This project adheres to strict code quality standards:
- Type hints throughout the codebase
- Comprehensive docstrings following Google style
- Error handling for numerical operations
## Dependencies
- NumPy: For numerical computations and linear algebra operations
- FastMCP: For Model Context Protocol server implementation
## License
This project is licensed under the MIT License.
## Acknowledgments
- NumPy team for their excellent scientific computing library
- Model Context Protocol (MCP) for enabling standardized LLM interactions
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
[project]
name = "math-mcp"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
"mcp[cli]>=1.3.0",
"numpy>=2.2.3",
]
```
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
```
annotated-types==0.7.0
anyio==4.8.0
certifi==2025.1.31
click==8.1.8
h11==0.14.0
httpcore==1.0.7
httpx==0.28.1
httpx-sse==0.4.0
idna==3.10
markdown-it-py==3.0.0
-e file:///Users/colesmcintosh/Projects/math-mcp
mcp==1.3.0
mdurl==0.1.2
numpy==2.2.3
pydantic==2.10.6
pydantic-core==2.27.2
pydantic-settings==2.8.1
pygments==2.19.1
python-dotenv==1.0.1
rich==13.9.4
shellingham==1.5.4
sniffio==1.3.1
sse-starlette==2.2.1
starlette==0.46.0
typer==0.15.2
typing-extensions==4.12.2
uvicorn==0.34.0
```
--------------------------------------------------------------------------------
/server.py:
--------------------------------------------------------------------------------
```python
# server.py
from typing import List, Union, Optional, Tuple
import numpy as np
from numpy.typing import NDArray
from mcp.server.fastmcp import FastMCP
# Create an MCP server
mcp = FastMCP("Numpy")
# Add an addition tool
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers.
Args:
a (int): First number to add
b (int): Second number to add
Returns:
int: Sum of the two numbers
"""
return a + b
@mcp.tool()
def matrix_multiply(
matrix_a: List[List[float]], matrix_b: List[List[float]]
) -> List[List[float]]:
"""Multiply two matrices using NumPy.
Args:
matrix_a (List[List[float]]): First input matrix
matrix_b (List[List[float]]): Second input matrix
Returns:
List[List[float]]: Result of matrix multiplication
Raises:
ValueError: If matrices have incompatible dimensions
"""
try:
result = np.matmul(np.array(matrix_a), np.array(matrix_b))
return result.tolist()
except ValueError as e:
raise ValueError(f"Matrix multiplication failed: {str(e)}") from e
@mcp.tool()
def statistical_analysis(
data: List[float]
) -> dict[str, float]:
"""Perform statistical analysis on a dataset.
Args:
data (List[float]): Input data for analysis
Returns:
dict[str, float]: Dictionary containing statistical measures
"""
arr = np.array(data)
return {
"mean": float(np.mean(arr)),
"median": float(np.median(arr)),
"std": float(np.std(arr)),
"min": float(np.min(arr)),
"max": float(np.max(arr))
}
@mcp.tool()
def eigen_decomposition(
matrix: List[List[float]]
) -> Tuple[List[float], List[List[float]]]:
"""Compute eigenvalues and eigenvectors of a square matrix.
Args:
matrix (List[List[float]]): Input square matrix
Returns:
Tuple[List[float], List[List[float]]]: Eigenvalues and eigenvectors
Raises:
ValueError: If matrix is not square or computation fails
"""
try:
arr = np.array(matrix)
eigenvalues, eigenvectors = np.linalg.eig(arr)
return eigenvalues.tolist(), eigenvectors.tolist()
except np.linalg.LinAlgError as e:
raise ValueError(f"Eigendecomposition failed: {str(e)}") from e
@mcp.tool()
def polynomial_fit(
x: List[float],
y: List[float],
degree: int = 2
) -> List[float]:
"""Fit a polynomial to the given data points.
Args:
x (List[float]): X coordinates
y (List[float]): Y coordinates
degree (int, optional): Degree of polynomial. Defaults to 2.
Returns:
List[float]: Coefficients of the fitted polynomial
"""
coefficients = np.polyfit(x, y, degree)
return coefficients.tolist()
```