SymPy Sandbox MCP

English | 中文版

A production-focused MCP service that lets agents/LLMs run SymPy safely and efficiently.
It combines AST policy checks, runtime resource limits, and prewarmed workers to deliver low-noise, parse-friendly results.

Features

• Single tool: sympy (input only requires code)
• Prewarmed worker pool to avoid repeated import sympy
• Two-layer safety: AST guard + runtime resource limits
• Compact structured JSON output for low token overhead
• Standardized error codes for reliable auto-retry workflows

Typical Use Cases

• Symbolic algebra, differentiation, integration, equation solving
• MCP tool integration for Codex / Cursor / Claude Desktop / custom MCP clients
• Agent workflows that need controllable failures and clean error signals

Recommended Integration (MCP client via stdio)

Call example:

fastmcp call \
  --command 'python -m sym_mcp.server' \
  --target sympy \
  --input-json '{"code":"import sympy as sp\\nx=sp.Symbol(\"x\")\\nprint(sp.factor(x**2-1))"}'

Client config (python -m, recommended):

{
  "mcpServers": {
    "sympy-sandbox": {
      "command": "python",
      "args": ["-m", "sym_mcp.server"]
    }
  }
}

Client config (installed as sym-mcp):

{
  "mcpServers": {
    "sympy-sandbox": {
      "command": "sym-mcp",
      "args": []
    }
  }
}

Client config (uvx):

{
  "mcpServers": {
    "sympy-sandbox": {
      "command": "uvx",
      "args": ["sym-mcp"]
    }
  }
}

Quick Start

1) Requirements

• Python 3.11+
• Linux / macOS (Linux recommended for production)

2) Install (Tsinghua mirror first)

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e .
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e ".[dev]"

3) Run server (stdio)

python -m sym_mcp.server

4) Verify tool

fastmcp list --command 'python -m sym_mcp.server'

Tool Contract

Tool name

• sympy

Input

• code: str

Notes:

• You must print() final outputs.
• If nothing is printed, out may be empty.

Output (always compact JSON string)

Success:

{"out":"x**2/2"}

Failure:

{"code":"E_RUNTIME","line":3,"err":"ZeroDivisionError: division by zero","hint":"Runtime error. Check variable types, division-by-zero, or undefined names near the reported line."}

Field definitions:

• out: stdout text on success
• code: error code
• line: user code error line, or null
• err: compact error message (traceback noise removed)
• hint: fix hint (based on configured hint level)
• If out / err / hint is too long, it will be truncated with ...[truncated]

Error Codes

• E_AST_BLOCK: blocked by AST safety policy
• E_SYNTAX: syntax error
• E_TIMEOUT: timeout
• E_MEMORY: memory limit triggered
• E_RUNTIME: general runtime error
• E_WORKER: worker communication/state failure
• E_INTERNAL: internal server error

Recommended Agent Prompt Rules

1. Use math-only Python code.
2. Only import sympy or math.
3. Always print() final answers.
4. For multiple outputs, use multiple print() lines.
5. On failure, patch minimally near line and retry.
6. For E_TIMEOUT, reduce scale first; for E_MEMORY, reduce object size/dimension; for E_AST_BLOCK, remove unsafe statements.

Example:

import sympy as sp
x = sp.Symbol("x")
expr = (x + 1)**5
print(sp.expand(expr))

Security Model

Before execution (AST policy)

• Only sympy / math imports are allowed
• Dangerous capabilities are blocked (eval, exec, open, __import__, etc.)
• Dunder attribute traversal is blocked (e.g. __class__)

During execution (OS resource limits)

• Per-task CPU time limit + timeout kill
• Per-worker memory limit via setrlimit
• Worker auto-rebuild on failure to keep server healthy

Architecture

• src/sym_mcp/server.py: MCP entrypoint and tool registration
• src/sym_mcp/security/ast_guard.py: AST validation
• src/sym_mcp/executor/worker_main.py: worker loop
• src/sym_mcp/executor/pool.py: async prewarmed process pool
• src/sym_mcp/executor/sandbox.py: restricted execution and stdout capture
• src/sym_mcp/errors/parser.py: error normalization and code mapping
• src/sym_mcp/config.py: runtime configuration

Configuration (Environment Variables)

• SYMMCP_POOL_SIZE: worker pool size, default 10
• SYMMCP_EXEC_TIMEOUT_SEC: per execution timeout (sec), default 3
• SYMMCP_MEMORY_LIMIT_MB: memory cap per worker (MB), default 150
• SYMMCP_QUEUE_WAIT_SEC: queue wait timeout (sec), default 2
• SYMMCP_LOG_LEVEL: log level, default INFO
• SYMMCP_MAX_OUTPUT_CHARS: output truncation threshold, default 1200
• SYMMCP_HINT_LEVEL: hint level (none/short/medium), default medium

FAQ

Why is out empty?

Most likely the code does not print() the final result.

Why return compact JSON string?

It is easier for agents to parse reliably and reduces token cost.

Is memory limiting always stable on macOS?

setrlimit behavior differs by OS. Linux is preferred for production.

Does it support HTTP/SSE?

Current primary delivery is stdio. HTTP/SSE can be added later via FastMCP transport extensions.

Known Limits

• This is restricted Python execution, not VM/container-grade isolation
• Memory limit behavior is OS-dependent
• Output is truncated at threshold, with ...[truncated] suffix

Development

Run tests

PYTHONPATH=src pytest -q

Benchmark

PYTHONPATH=src python scripts/benchmark.py --concurrency 100 --total 500

Contributing

• Run PYTHONPATH=src pytest -q before submitting PRs
• When adding new capabilities, update:
  • error code docs
  • README examples
  • related unit/integration tests
• Publishing process: PUBLISHING.md