MathematicalMethods 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.

Quick start

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

Any MCP client registers the server with the same one-liner command — uvx mathmethods-mcp (a Python package that needs no cloning, venv or paths):

{ "command": "uvx", "args": ["mathmethods"] }

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

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 α β γ ε μ δ.

Project layout

modelo-mat-mcp/
├── server.py                 # FastMCP app + all tools
├── mathmethods/
│   ├── compiler.py           # hardened expression validation (whitelist, caps)
│   ├── 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
├── mcp.example.json          # server registration template (copy to .vscode/mcp.json)
├── requirements.txt
└── pyproject.toml

Install

cd modelo-mat-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": {
    "modelo-mat-stdio": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mathmethods"]
    },
    "modelo-mat-http": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

{
  "context_servers": {
    "modelo-mat": {
      "command": "uvx",
      "args": ["mathmethods"]
    }
  }
}

{
  "mcp": {
    "modelo-mat": {
      "type": "local",
      "command": ["uvx", "mathmethods"],
      "enabled": true
    }
  }
}

opencode mcp add modelo-mat -- uvx mathmethods-mcp

{
  "mcp": {
    "modelo-mat": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp",
      "enabled": true
    }
  }
}

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

copilot

/mcp add
  Server name:  modelo-mat
  Server type:  1 (Local/STDIO)
  Command:      uvx mathmethods-mcp

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

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

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.