# Directory Structure
```
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
├── requirements.txt
├── server.py
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/.python-version:
--------------------------------------------------------------------------------
```
1 | 3.13
2 |
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Python-generated files
2 | __pycache__/
3 | *.py[oc]
4 | build/
5 | dist/
6 | wheels/
7 | *.egg-info
8 |
9 | # Virtual environments
10 | .venv
11 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | [](https://mseep.ai/app/colesmcintosh-numpy-mcp)
2 |
3 | # NumPy MCP Server
4 |
5 | <div align="center">
6 |
7 | <strong>A Model Context Protocol (MCP) server for numerical computations with NumPy</strong>
8 |
9 | [![MIT licensed][mit-badge]][mit-url]
10 |
11 | </div>
12 |
13 | [mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
14 | [mit-url]: ./LICENSE
15 | [python-badge]: https://img.shields.io/badge/python-3.8%2B-blue.svg
16 | [python-url]: https://www.python.org/downloads/
17 |
18 | 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.
19 |
20 | ## Features
21 |
22 | - Basic arithmetic operations (addition)
23 | - Linear algebra computations (matrix multiplication, eigendecomposition)
24 | - Statistical analysis (mean, median, standard deviation, min, max)
25 | - Polynomial fitting
26 |
27 | ## Installation
28 |
29 | ### Quick Setup with Claude Desktop
30 |
31 | The fastest way to get started is to install this server directly in Claude Desktop:
32 |
33 | ```bash
34 | # Install the server in Claude Desktop
35 | mcp install server.py --name "NumPy Calculator"
36 | ```
37 |
38 | ### Manual Installation
39 |
40 | This project uses UV for dependency management. To install:
41 |
42 | ```bash
43 | # Install UV if you haven't already
44 | curl -LsSf https://astral.sh/uv/install.sh | sh
45 |
46 | # Clone the repository
47 | git clone https://github.com/yourusername/math-mcp.git
48 | cd math-mcp
49 |
50 | # Create virtual environment and install dependencies
51 | uv venv
52 | source .venv/bin/activate # On Unix/macOS
53 | # or
54 | # .venv\Scripts\activate # On Windows
55 | uv pip install -r requirements.txt
56 | ```
57 |
58 | ## Usage
59 |
60 | ### Development Testing
61 |
62 | Test the server locally with the MCP Inspector:
63 |
64 | ```bash
65 | mcp dev server.py
66 | ```
67 |
68 | ### Claude Desktop Integration
69 |
70 | 1. Install the server in Claude Desktop:
71 | ```bash
72 | mcp install server.py --name "NumPy Calculator"
73 | ```
74 |
75 | 2. The server will now be available in Claude Desktop under "NumPy Calculator"
76 |
77 | 3. You can use it by asking Claude to perform mathematical operations, for example:
78 | - "Calculate the eigenvalues of matrix [[1, 2], [3, 4]]"
79 | - "Find the mean and standard deviation of [1, 2, 3, 4, 5]"
80 | - "Multiply matrices [[1, 0], [0, 1]] and [[2, 3], [4, 5]]"
81 |
82 | ### Direct Execution
83 |
84 | For advanced usage or custom deployments:
85 |
86 | ```bash
87 | python server.py
88 | # or
89 | mcp run server.py
90 | ```
91 |
92 | ## Available Functions
93 |
94 | The server provides the following mathematical functions through the MCP interface:
95 |
96 | ### Basic Arithmetic
97 |
98 | - `add(a: int, b: int) -> int`: Add two integers together
99 |
100 | ### Linear Algebra
101 |
102 | - `matrix_multiply(matrix_a: List[List[float]], matrix_b: List[List[float]]) -> List[List[float]]`: Multiply two matrices
103 | - `eigen_decomposition(matrix: List[List[float]]) -> Tuple[List[float], List[List[float]]]`: Compute eigenvalues and eigenvectors of a square matrix
104 |
105 | ### Statistics
106 |
107 | - `statistical_analysis(data: List[float]) -> dict[str, float]`: Calculate basic statistics for a dataset including:
108 | - Mean
109 | - Median
110 | - Standard deviation
111 | - Minimum value
112 | - Maximum value
113 |
114 | ### Data Analysis
115 |
116 | - `polynomial_fit(x: List[float], y: List[float], degree: int = 2) -> List[float]`: Fit a polynomial of specified degree to the given data points
117 |
118 | ## Development
119 |
120 | ### Project Structure
121 |
122 | ```
123 | math-mcp/
124 | ├── requirements.txt
125 | ├── README.md
126 | └── server.py
127 | ```
128 |
129 | ### Code Quality
130 |
131 | This project adheres to strict code quality standards:
132 | - Type hints throughout the codebase
133 | - Comprehensive docstrings following Google style
134 | - Error handling for numerical operations
135 |
136 | ## Dependencies
137 |
138 | - NumPy: For numerical computations and linear algebra operations
139 | - FastMCP: For Model Context Protocol server implementation
140 |
141 | ## License
142 |
143 | This project is licensed under the MIT License.
144 |
145 | ## Acknowledgments
146 |
147 | - NumPy team for their excellent scientific computing library
148 | - Model Context Protocol (MCP) for enabling standardized LLM interactions
149 |
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
1 | [project]
2 | name = "math-mcp"
3 | version = "0.1.0"
4 | description = "Add your description here"
5 | readme = "README.md"
6 | requires-python = ">=3.13"
7 | dependencies = [
8 | "mcp[cli]>=1.3.0",
9 | "numpy>=2.2.3",
10 | ]
11 |
```
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
```
1 | annotated-types==0.7.0
2 | anyio==4.8.0
3 | certifi==2025.1.31
4 | click==8.1.8
5 | h11==0.14.0
6 | httpcore==1.0.7
7 | httpx==0.28.1
8 | httpx-sse==0.4.0
9 | idna==3.10
10 | markdown-it-py==3.0.0
11 | -e file:///Users/colesmcintosh/Projects/math-mcp
12 | mcp==1.3.0
13 | mdurl==0.1.2
14 | numpy==2.2.3
15 | pydantic==2.10.6
16 | pydantic-core==2.27.2
17 | pydantic-settings==2.8.1
18 | pygments==2.19.1
19 | python-dotenv==1.0.1
20 | rich==13.9.4
21 | shellingham==1.5.4
22 | sniffio==1.3.1
23 | sse-starlette==2.2.1
24 | starlette==0.46.0
25 | typer==0.15.2
26 | typing-extensions==4.12.2
27 | uvicorn==0.34.0
28 |
```
--------------------------------------------------------------------------------
/server.py:
--------------------------------------------------------------------------------
```python
1 | # server.py
2 | from typing import List, Union, Optional, Tuple
3 | import numpy as np
4 | from numpy.typing import NDArray
5 | from mcp.server.fastmcp import FastMCP
6 |
7 | # Create an MCP server
8 | mcp = FastMCP("Numpy")
9 |
10 | # Add an addition tool
11 | @mcp.tool()
12 | def add(a: int, b: int) -> int:
13 | """Add two numbers.
14 |
15 | Args:
16 | a (int): First number to add
17 | b (int): Second number to add
18 |
19 | Returns:
20 | int: Sum of the two numbers
21 | """
22 | return a + b
23 |
24 | @mcp.tool()
25 | def matrix_multiply(
26 | matrix_a: List[List[float]], matrix_b: List[List[float]]
27 | ) -> List[List[float]]:
28 | """Multiply two matrices using NumPy.
29 |
30 | Args:
31 | matrix_a (List[List[float]]): First input matrix
32 | matrix_b (List[List[float]]): Second input matrix
33 |
34 | Returns:
35 | List[List[float]]: Result of matrix multiplication
36 |
37 | Raises:
38 | ValueError: If matrices have incompatible dimensions
39 | """
40 | try:
41 | result = np.matmul(np.array(matrix_a), np.array(matrix_b))
42 | return result.tolist()
43 | except ValueError as e:
44 | raise ValueError(f"Matrix multiplication failed: {str(e)}") from e
45 |
46 | @mcp.tool()
47 | def statistical_analysis(
48 | data: List[float]
49 | ) -> dict[str, float]:
50 | """Perform statistical analysis on a dataset.
51 |
52 | Args:
53 | data (List[float]): Input data for analysis
54 |
55 | Returns:
56 | dict[str, float]: Dictionary containing statistical measures
57 | """
58 | arr = np.array(data)
59 | return {
60 | "mean": float(np.mean(arr)),
61 | "median": float(np.median(arr)),
62 | "std": float(np.std(arr)),
63 | "min": float(np.min(arr)),
64 | "max": float(np.max(arr))
65 | }
66 |
67 | @mcp.tool()
68 | def eigen_decomposition(
69 | matrix: List[List[float]]
70 | ) -> Tuple[List[float], List[List[float]]]:
71 | """Compute eigenvalues and eigenvectors of a square matrix.
72 |
73 | Args:
74 | matrix (List[List[float]]): Input square matrix
75 |
76 | Returns:
77 | Tuple[List[float], List[List[float]]]: Eigenvalues and eigenvectors
78 |
79 | Raises:
80 | ValueError: If matrix is not square or computation fails
81 | """
82 | try:
83 | arr = np.array(matrix)
84 | eigenvalues, eigenvectors = np.linalg.eig(arr)
85 | return eigenvalues.tolist(), eigenvectors.tolist()
86 | except np.linalg.LinAlgError as e:
87 | raise ValueError(f"Eigendecomposition failed: {str(e)}") from e
88 |
89 | @mcp.tool()
90 | def polynomial_fit(
91 | x: List[float],
92 | y: List[float],
93 | degree: int = 2
94 | ) -> List[float]:
95 | """Fit a polynomial to the given data points.
96 |
97 | Args:
98 | x (List[float]): X coordinates
99 | y (List[float]): Y coordinates
100 | degree (int, optional): Degree of polynomial. Defaults to 2.
101 |
102 | Returns:
103 | List[float]: Coefficients of the fitted polynomial
104 | """
105 | coefficients = np.polyfit(x, y, degree)
106 | return coefficients.tolist()
```