Mathematical/Numerical Methods - MCP Server

A Model Context Protocol server that exposes a numerical-methods core as tools an LLM agent can call directly from a chat (VS Code, Zed, Claude, opencode, etc.). It is built on top of the numerical-methods engine of the academic project modeladoYsimulacion-web (UADE); the math core is vendored into this repository so the server is fully self-contained.

Installation and Usage

1. Run with NPX (Recommended)

Runs on-demand without any global installation:

Claude Code (One-liner CLI)

claude mcp add mathmethods npx -y @agmonetti/mathmethods-mcp

Claude Desktop & Cursor (JSON Configuration)

Add to your claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "mathmethods": {
      "command": "npx",
      "args": ["-y", "@agmonetti/mathmethods-mcp"]
    }
  }
}

2. Install Globally from NPM

Ideal for instant startup without network latency on every invocation:

npm install -g @agmonetti/mathmethods-mcp

{
  "mcpServers": {
    "mathmethods": {
      "command": "mathmethods-mcp"
    }
  }
}

3. Run with UVX (Direct Python)

Any MCP client can also run the Python package directly with Astral's uvx:

claude mcp add mathmethods-mcp -- uvx mathmethods-mcp

{
  "mcpServers": {
    "mathmethods": {
      "command": "uvx",
      "args": ["mathmethods-mcp"]
    }
  }
}

git clone https://github.com/agmonetti/mathmethods-mcp.git
cd mathmethods-mcp
uv sync --extra dev
uv run server.py

Tools

Root finding

Numerical integration

Differentiation

ODE and interpolation

Monte Carlo

Dynamic systems

Math expressions use Python/SymPy syntax: x**2, sin(x), exp(x), sqrt(x), log(x). Common shorthand is accepted too: e^x, sen(x), ln(x) and the caret ^ for powers. The Greek combat parameters of Lanchester use the Unicode symbols α β γ ε μ δ.

Plots (optional)

Every tool accepts a plot=False | True flag. With plot=True the response contains the usual JSON plus a rendered PNG (an MCP image content block): phase portraits, solution curves, bifurcation diagrams, Monte Carlo convergence, and so on.

"Solve y' = y, y(0)=1 on [0,1] with RK4 and show me the plot."

Plotting needs the optional viz extra (Matplotlib), which is not part of the default install so the stdio server startup stays light:

pip install "mathmethods-mcp[viz]"    # pip
uvx --from "mathmethods-mcp[viz]" mathmethods-mcp   # uv
uv sync --extra viz                   # from a checkout

If plot=True is used without the extra, the tool returns a clear error telling you how to install it. Clients that do not render images still receive the JSON result alongside the image, so nothing is lost.

Project layout

mathmethods-mcp/
├── server.py                 # FastMCP app + all tools
├── mathmethods/
│   ├── compiler.py           # hardened expression validation (whitelist, caps)
│   ├── plots.py              # optional PNG rendering (plot=True), lazy matplotlib
│   ├── server.py             # FastMCP app and tool definitions
│   └── core/                 # vendored math core (from modeladoYsimulacion-web)
│       ├── root_finding.py   ├── integration.py
│       ├── ode.py            ├── interpolation.py
│       ├── differentiation.py├── monte_carlo.py
│       ├── dynamic_1d.py     ├── dynamic_2d_linear.py
│       ├── dynamic_2d_non_homogeneous.py ├── dynamic_2d_nonlinear.py
│       ├── dynamic_2d_conservative.py ├── dynamic_2d_lanchester.py
│       └── utils.py
├── tests/                    # test_tools.py + test_dynamic_tools.py + test_plots.py
├── mcp.example.json          # server registration template (copy to .vscode/mcp.json)
├── requirements.txt
└── pyproject.toml

Install

cd mathmethods-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

After creating the venv, verify it is isolated (venv/bin/python -c "import sys; print(sys.prefix)" should print the venv path, not /usr). If your system Python produces a broken venv, try python3 -m venv --copies venv.

Run

Local (STDIO) — default transport, used by VS Code / Claude Desktop:

uv run python server.py

Remote (Streamable HTTP) — the server prints a URL such as http://127.0.0.1:8000/mcp:

MCP_TRANSPORT=streamable-http uv run python server.py

The transport can also be chosen with the MCP_TRANSPORT environment variable (stdio | streamable-http | sse), and the HTTP host/port with MCP_HTTP_HOST / MCP_HTTP_PORT (defaults 127.0.0.1:8000).

Connect from a client

Every client registers the same command, uvx mathmethods-mcp (no paths, no venv). If the server is not published yet or you work from a checkout, use uv run --frozen --project <PROJ> python <PROJ>/server.py instead.

Remote (Streamable HTTP) — optional; start it once in a terminal, then point the client at http://127.0.0.1:8000/mcp:

MCP_TRANSPORT=streamable-http uvx mathmethods-mcp

{
  "servers": {
    "mathmethods-stdio": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@agmonetti/mathmethods-mcp"]
    },
    "mathmethods-http": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

{
  "context_servers": {
    "mathmethods": {
      "command": "npx",
      "args": ["-y", "@agmonetti/mathmethods-mcp"]
    }
  }
}

{
  "mcp": {
    "mathmethods": {
      "type": "local",
      "command": ["npx", "-y", "@agmonetti/mathmethods-mcp"],
      "enabled": true
    }
  }
}

opencode mcp add mathmethods -- npx -y @agmonetti/mathmethods-mcp

{
  "mcp": {
    "mathmethods": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp",
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "mathmethods": {
      "command": "npx",
      "args": ["-y", "@agmonetti/mathmethods-mcp"]
    }
  }
}

copilot

/mcp add
  Server name:  mathmethods
  Server type:  1 (Local/STDIO)
  Command:      npx -y @agmonetti/mathmethods-mcp

claude mcp add mathmethods npx -y @agmonetti/mathmethods-mcp

{
  "mcpServers": {
    "mathmethods": {
      "command": "npx",
      "args": ["-y", "@agmonetti/mathmethods-mcp"]
    }
  }
}

Verify with the MCP Inspector

npx @modelcontextprotocol/inspector node server.py   # or
npx @modelcontextprotocol/inspector --transport http http://127.0.0.1:8000/mcp

Example usage

Ask your agent things like:

• "Find the root of x^3 - 3x + 1 in [0, 1]."
• "Integrate sin(x)/x from 0 to 1 using Simpson with n=10."
• "Solve y' = y with y(0)=1 from x=0 to x=1 with step 0.1 (RK4)."
• "Build the Lagrange polynomial through (0,1), (1,3), (2,7) and evaluate at 1.5."
• "Estimate the integral of sin(x) over [0, 2pi] with Monte Carlo hit-or-miss."
• "Find the equilibria of the logistic model x' = mu*x*(1 - x/K) with K=2, mu=1."
• "Classify the 2D system x' = 2x - y, y' = x + 2y and sketch its trajectories."
• "Simulate a Lanchester battle x'=-αy, y'=-βx with α=1, β=2, 100 vs 80 soldiers."

Security

The server is read-only: the tools only compute numbers, they never touch the filesystem, the network or any destructive operation. Still, the inputs are driven by an LLM, so defense in depth is applied:

• Expression hardening (mathmethods/compiler.py + mathmethods/core/utils.py): length cap, symbol whitelist, function whitelist, and a lexical gate that rejects attribute access (./__) and unknown tokens BEFORE SymPy parses. SymPy's sympify/parse_expr can execute arbitrary Python (verified RCE), so every parse site — in this project and in the upstream backend — routes through the gate.
• Input caps: iteration/subinterval/step/point counts are bounded to avoid pathological CPU/RAM usage.
• Exact tool descriptions: the LLM picks tools by their metadata, so descriptions stay accurate (guards against tool-poisoning attacks).
• Prompt injection: even if the model is tricked, the worst it can do is ask for another computation. There are no privileged side channels.

Known limitations

• The vendored core is inherited from the upstream project and kept as-is (Spanish identifiers, etc.).
• dynamic_2d_nonhomogeneous_solve with time-varying forcing on a non-diagonal matrix A shows the homogeneous solution only (the particular term is computed for diagonal systems); the numeric RK4 trajectory is always correct.
• The 1D bifurcation table is downsampled to 300 rows for readability.

Publishing to PyPI

The package is publish-ready (uv build succeeds and the wheel exposes all tools). To release:

uv build
uv publish          # requires a PyPI token: `uv login` or UV_PUBLISH_TOKEN

Once published, every client config just works with uvx mathmethods-mcp (no paths, no venv). Bump version in pyproject.toml before each release.

Keeping the vendored core in sync

The math lives in modeladoYsimulacion-web/backend/app/methods/. When the upstream code changes, copy the files here again:

cp ../modeladoYsimulacion-web/backend/app/methods/{root_finding,integration,ode,interpolation,monte_carlo,dynamic_1d,dynamic_2d_linear,dynamic_2d_non_homogeneous,dynamic_2d_nonlinear,dynamic_2d_conservative,dynamic_2d_lanchester}.py mathmethods/core/
cp ../modeladoYsimulacion-web/backend/app/core/utils.py mathmethods/core/utils.py

Then rewrite the from app.core.utils import ... imports to from .utils import ... in the copied files.

Test

uv run pytest

Roadmap

• Translate the vendored core to English (manual, when time allows).
• Server-side CI is wired up (.github/workflows/ci.yml); coverage report next.
• Optional MCP resources/prompts (e.g. a theorem reference) on top of the tools.