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.

Releasing

Releases are automated: bump the version, push a tag, and both registries are updated by CI. No tokens or repository secrets are stored — PyPI and npm use GitHub OIDC (Trusted Publishing).

1. Bump the version in three places (they must match the tag): pyproject.toml, mathmethods/__init__.py and package.json.

2. Refresh the lockfile — CI runs uv lock --check, and the lock records the project version, so forgetting this breaks the build:

   uv lock

3. Add an entry to CHANGELOG.md.

4. Commit and push, then tag:

   git commit -am "chore: release v0.3.0"
   git tag v0.3.0 && git push origin main --tags

Pushing a v* tag runs .github/workflows/release.yml, which:

• runs the full CI suite (test + viz) — a red commit can never be released;
• verifies the tag matches the version in pyproject.toml and package.json;
• builds the sdist + wheel in a credential-free job, then publishes them to PyPI;
• publishes the wrapper to npm (@agmonetti/mathmethods-mcp) with an automatic provenance attestation.

One-time Trusted Publisher setup

Configure these once; afterwards every tag publishes with no manual step.

PyPI — project mathmethods-mcp → Settings → Publishing → add a trusted publisher:

npm — package @agmonetti/mathmethods-mcp → Settings → Trusted Publisher:

npm gotchas. A trusted publisher created after 2026-09-03 defaults to stage publish only — tick npm publish or the release fails with ENEEDAUTH. A brand-new trusted publisher expires if it does not get a successful publish within 2 days, so set it up right before the first release. While there, set Publishing access to require 2FA and disallow tokens.

Manual fallback

If you ever need to publish by hand (e.g. before the tag exists):

uv build                       # sdist + wheel in dist/
uv publish                     # uses UV_PUBLISH_TOKEN or `uv login`
npm publish --access public    # requires `npm login`

Once published, every client config just works with uvx mathmethods-mcp (no paths, no venv).

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.