Skip to content
Back to search

sympy-mcp

A MCP server for symbolic manipulation of mathematical expressions

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sdiehl--sympy-mcp/badge.svg)](/listings/sdiehl--sympy-mcp)

HTML

<a href="/listings/sdiehl--sympy-mcp"><img src="/api/listings/sdiehl--sympy-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

In your `~/.cursor/mcp.json`, add the following, where `ABSOLUTE_PATH_TO_SYMPY_MCP` is the path to the sympy-mcp server.py file.

{
  "mcpServers": {
    "sympy-mcp": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run",
        "--with",
        "einsteinpy",
        "--with",
        "mcp[cli]",
        "--with",
        "pydantic",
        "--with",
        "sympy",
        "mcp",
        "run",
        "/ABSOLUTE_PATH_TO_SYMPY_MCP/server.py"
      ]
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 458 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Symbolic Algebra MCP Server
  2. **This library is no longer maintained. It is Apache licensed, so feel free to fork it.**
  3. Sympy-MCP is a Model Context Protocol server for allowing LLMs to autonomously perform symbolic mathematics and computer algebra. It exposes numerous tools from SymPy's core functionality to MCP clients for manipulating mathematical expressions and equations.
  4. ## Why?
  5. Language models are absolutely abysmal at symbolic manipulation. They hallucinate variables, make up random constants, permute terms and generally make a mess. But we have computer algebra systems specifically built for symbolic manipulation, so we can use tool-calling to orchestrate a sequence of transforms so that the symbolic kernel does all the heavy lifting.
  6. While you can certainly have an LLM generate Mathematica or Python code, if you want to use the LLM as an agent or on-the-fly calculator, it's a better experience to use the MCP server and expose the symbolic tools directly.
  7. The server exposes a subset of symbolic mathematics capabilities including algebraic equation solving, integration and differentiation, vector calculus, tensor calculus for general relativity, and both ordinary and partial differential equations.
  8. For example, you can ask it in natural language to solve a differential equation:
  9. > Solve the damped harmonic oscillator with forcing term: the mass-spring-damper system described by the differential equation where m is mass, c is the damping coefficient, k is the spring constant, and F(t) is an external force.
  10. $$ m\frac{d^2x}{dt^2} + c\frac{dx}{dt} + kx = F(t) $$
  11. Or involving general relativity:
  12. > Compute the trace of the Ricci tensor $R_{\mu\nu}$ using the inverse metric $g^{\mu\nu}$ for Anti-de Sitter spacetime to determine its constant scalar curvature $R$.
  13. ## Usage
  14. You need [uv](https://docs.astral.sh/uv/getting-started/installation/) first.
  15. - **Homebrew** : `brew install uv`
  16. - **Curl** : `curl -LsSf https://astral.sh/uv/install.sh | sh`
  17. Then you can install and run the server with the following commands:
  18. ```shell
  19. # Setup the project
  20. git clone https://github.com/sdiehl/sympy-mcp.git
  21. cd sympy-mcp
  22. uv sync
  23. # Install the server to Claude Desktop
  24. uv run mcp install server.py
  25. # Run the server
  26. uv run mcp run server.py
  27. ```
  28. You should see the server available in the Claude Desktop app now. For other clients, see below.
  29. If you want a completely standalone version that just runs with a single command, you can use the following. *Note this is running arbitrary code from Github, so be careful.*
  30. ```shell
  31. uv run --with https://github.com/sdiehl/sympy-mcp/releases/download/0.1/sympy_mcp-0.1.0-py3-none-any.whl python server.py
  32. ```
  33. If you want to do general relativity calculations, you need to install the [`einsteinpy`](https://github.com/einsteinpy/einsteinpy) library.
  34. ```shell
  35. uv sync --group relativity
  36. ```
  37. ## Available Tools
  38. The sympy-mcp server provides the following tools for symbolic mathematics:
  39. | Tool | Tool ID | Description |
  40. |------|-------|-------------|
  41. | Variable Introduction | `intro` | Introduces a variable with specified assumptions and stores it |
  42. | Multiple Variables | `intro_many` | Introduces multiple variables with specified assumptions simultaneously |
  43. | Expression Parser | `introduce_expression` | Parses an expression string using available local variables and stores it |
  44. | LaTeX Printer | `print_latex_expression` | Prints a stored expression in LaTeX format, along with variable assumptions |
  45. | Algebraic Solver | `solve_algebraically` | Solves an equation algebraically for a given variable over a given domain |
  46. | Linear Solver | `solve_linear_system` | Solves a system of linear equations |
  47. | Nonlinear Solver | `solve_nonlinear_system` | Solves a system of nonlinear equations |
  48. | Function Variable | `introduce_function` | Introduces a function variable for use in differential equations |
  49. | ODE Solver | `dsolve_ode` | Solves an ordinary differential equation |
  50. | PDE Solver | `pdsolve_pde` | Solves a partial differential equation |
  51. | Standard Metric | `create_predefined_metric` | Creates a predefined spacetime metric (e.g. Schwarzschild, Kerr, Minkowski) |
  52. | Metric Search | `search_predefined_metrics` | Searches available predefined metrics |
  53. | Tensor Calculator | `calculate_tensor` | Calculates tensors from a metric (Ricci, Einstein, Weyl tensors) |
  54. | Custom Metric | `create_custom_metric` | Creates a custom metric tensor from provided components and symbols |
  55. | Tensor LaTeX | `print_latex_tensor` | Prints a stored tensor expression in LaTeX format |
  56. | Simplifier | `simplify_expression` | Simplifies a mathematical expression using SymPy's canonicalize function |
  57. | Substitution | `substitute_expression` | Substitutes a variable with an expression in another expression |
  58. | Integration | `integrate_expression` | Integrates an expression with respect to a variable |
  59. | Differentiation | `differentiate_expression` | Differentiates an expression with respect to a variable |
  60. | Coordinates | `create_coordinate_system` | Creates a 3D coordinate system for vector calculus operations |
  61. | Vector Field | `create_vector_field` | Creates a vector field in the specified coordinate system |
  62. | Curl | `calculate_curl` | Calculates the curl of a vector field |
  63. | Divergence | `calculate_divergence` | Calculates the divergence of a vector field |
  64. | Gradient | `calculate_gradient` | Calculates the gradient of a scalar field |
  65. | Unit Converter | `convert_to_units` | Converts a quantity to given target units |
  66. | Unit Simplifier | `quantity_simplify_units` | Simplifies a quantity with units |
  67. | Matrix Creator | `create_matrix` | Creates a SymPy matrix from the provided data |
  68. | Determinant | `matrix_determinant` | Calculates the determinant of a matrix |
  69. | Matrix Inverse | `matrix_inverse` | Calculates the inverse of a matrix |
  70. | Eigenvalues | `matrix_eigenvalues` | Calculates the eigenvalues of a matrix |
  71. | Eigenvectors | `matrix_eigenvectors` | Calculates the eigenvectors of a matrix |
  72. By default variables are predefined with assumptions (similar to how the [symbols()](https://docs.sympy.org/latest/modules/core.html#sympy.core.symbol.symbols) function works in SymPy). Unless otherwise specified the defaut assumptions is that a variable is complex, commutative, term over the complex field $\mathbb{C}$.
  73. | Property | Value |
  74. |----------|-------|
  75. | `commutative` | true |
  76. | `complex` | true |
  77. | `finite` | true |
  78. | `infinite` | false |
  79. ## Claude Desktop Setup
  80. Normally the `mcp install` command will automatically add the server to the `claude_desktop_config.json` file. If it doesn't you need to find the config file and add the following:
  81. * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  82. * Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  83. Add the following to the `mcpServers` object, replacing `/ABSOLUTE_PATH_TO_SYMPY_MCP/server.py` with the absolute path to the sympy-mcp `server.py` file.
  84. ```json
  85. {
  86. "mcpServers": {
  87. "sympy-mcp": {
  88. "command": "/opt/homebrew/bin/uv",
  89. "args": [
  90. "run",
  91. "--with",
  92. "einsteinpy",
  93. "--with",
  94. "mcp[cli]",
  95. "--with",
  96. "pydantic",
  97. "--with",
  98. "sympy",
  99. "mcp",
  100. "run",
  101. "/ABSOLUTE_PATH_TO_SYMPY_MCP/server.py"
  102. ]
  103. }
  104. }
  105. }
  106. ```
  107. ## Cursor Setup
  108. In your `~/.cursor/mcp.json`, add the following, where `ABSOLUTE_PATH_TO_SYMPY_MCP` is the path to the sympy-mcp server.py file.
  109. ```json
  110. {
  111. "mcpServers": {
  112. "sympy-mcp": {
  113. "command": "/opt/homebrew/bin/uv",
  114. "args": [
  115. "run",
  116. "--with",
  117. "einsteinpy",
  118. "--with",
  119. "mcp[cli]",
  120. "--with",
  121. "pydantic",
  122. "--with",
  123. "sympy",
  124. "mcp",
  125. "run",
  126. "/ABSOLUTE_PATH_TO_SYMPY_MCP/server.py"
  127. ]
  128. }
  129. }
  130. }
  131. ```
  132. ## VS Code Setup
  133. VS Code and VS Code Insiders now support MCPs in [agent mode](https://code.visualstudio.com/blogs/2025/04/07/agentMode). For VS Code, you may need to enable `Chat > Agent: Enable` in the settings.
  134. 1. **One-click Setup:**
  135. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=sympy-mcp&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22-p%22%2C%228081%3A8081%22%2C%22--rm%22%2C%22ghcr.io%2Fsdiehl%2Fsympy-mcp%3Amain%22%5D%7D)
  136. [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=sympy-mcp&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22-p%22%2C%228081%3A8081%22%2C%22--rm%22%2C%22ghcr.io%2Fsdiehl%2Fsympy-mcp%3Amain%22%5D%7D&quality=insiders)
  137. OR manually add the config to your `settings.json` (global):
  138. ```json
  139. {
  140. "mcp": {
  141. "servers": {
  142. "sympy-mcp": {
  143. "command": "uv",
  144. "args": [
  145. "run",
  146. "--with",
  147. "einsteinpy",
  148. "--with",
  149. "mcp[cli]",
  150. "--with",
  151. "pydantic",
  152. "--with",
  153. "sympy",
  154. "mcp",
  155. "run",
  156. "/ABSOLUTE_PATH_TO_SYMPY_MCP/server.py"
  157. ]
  158. }
  159. }
  160. }
  161. }
  162. ```
  163. 2. Click "Start" above the server config switch to agent mode in the chat, and try commands like "integrate x^2" or "solve x^2 = 1" to get started.
  164. ## HTTP Transport (Streamable HTTP / SSE)
  165. The server supports MCP over HTTP using the [streamable-http transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) introduced in MCP spec 2025-03-26. This replaces the legacy SSE transport and exposes a single `/mcp` endpoint that clients connect to over HTTP.
  166. This is the recommended transport when running the server as a standalone process or in a container, because it allows any HTTP-capable MCP client to connect without needing to launch the server as a subprocess.
  167. ```bash
  168. # Run locally with HTTP transport
  169. uv run python server.py --transport streamable-http
  170. # Override host/port
  171. uv run python server.py --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 9000
  172. ```
  173. The legacy `--transport sse` flag is still supported for backward compatibility.
  174. A `/healthcheck` endpoint is also exposed that runs a full MCP protocol round-trip (initialize → tools/list → session teardown) and returns `{"status": "ok", "tool_count": N}`.
  175. ## Running in Container
  176. You can build and run the server using Docker locally:
  177. ```bash
  178. # Build the Docker image
  179. docker build -t sympy-mcp .
  180. # Run the Docker container
  181. docker run -p 8081:8081 sympy-mcp
  182. ```
  183. Or use Docker Compose from the `docker/` directory:
  184. ```bash
  185. cd docker
  186. docker compose up -d --build
  187. ```
  188. Alternatively, you can pull the pre-built image from GitHub Container Registry:
  189. ```bash
  190. # Pull the latest image
  191. docker pull ghcr.io/sdiehl/sympy-mcp:main
  192. # Run the container
  193. docker run -p 8081:8081 --rm ghcr.io/sdiehl/sympy-mcp:main
  194. ```
  195. To configure Claude Desktop to launch the Docker container, edit your `claude_desktop_config.json` file:
  196. ```json
  197. {
  198. "mcpServers": {
  199. "sympy-mcp": {
  200. "command": "docker",
  201. "args": [
  202. "run",
  203. "-i",
  204. "-p",
  205. "8081:8081",
  206. "--rm",
  207. "sympy-mcp"
  208. ]
  209. }
  210. }
  211. }
  212. ```
  213. Or to use the pre-built container from GitHub:
  214. ```json
  215. {
  216. "mcpServers": {
  217. "sympy-mcp": {
  218. "command": "docker",
  219. "args": [
  220. "run",
  221. "-i",
  222. "-p",
  223. "8081:8081",
  224. "--rm",
  225. "ghcr.io/sdiehl/sympy-mcp:main"
  226. ]
  227. }
  228. }
  229. }
  230. ```
  231. This configuration tells Claude Desktop to launch the Docker container when needed. Make sure to build the Docker image (`docker build -t sympy-mcp .`) before using Claude Desktop with this configuration.
  232. The other installation methods can also be adapted to work with Docker if you change the uv command to use the docker run command instead.
  233. ## Example Interaction 1 : Differential Equations
  234. Here's an example of how the tool-calling works in a conversation with an AI assistant using this MCP server:
  235. **User**: Solve the damped harmonic oscillator with forcing term: the mass-spring-damper system described by the differential equation where m is mass, c is the damping coefficient, k is the spring constant, and F(t) is an external force.
  236. $$ m\frac{d^2x}{dt^2} + c\frac{dx}{dt} + kx = F(t) $$
  237. **Assistant**: (Internal tool call) `intro_many` to introduce variables:
  238. ```json
  239. {
  240. "variables": [
  241. {"var_name": "t", "pos_assumptions": ["real"], "neg_assumptions": []},
  242. {"var_name": "m", "pos_assumptions": ["real", "positive"], "neg_assumptions": []},
  243. {"var_name": "c", "pos_assumptions": ["real", "positive"], "neg_assumptions": []},
  244. {"var_name": "k", "pos_assumptions": ["real", "positive"], "neg_assumptions": []}
  245. ]
  246. }
  247. ```
  248. **Assistant**: (Internal tool call) `introduce_function` to define x(t):
  249. ```json
  250. {
  251. "func_name": "x"
  252. }
  253. ```
  254. **Assistant**: (Internal tool call) `introduce_expression` to create the differential equation:
  255. ```json
  256. {
  257. "expr_str": "Eq(m*Derivative(x(t), t, t) + c*Derivative(x(t), t) + k*x(t), F(t))"
  258. }
  259. ```
  260. **Assistant**: (Internal tool call) `print_latex_expression` to display the equation nicely:
  261. ```json
  262. {
  263. "expr_key": "expr_12"
  264. }
  265. ```
  266. Result:
  267. $$
  268. c \frac{d}{d t} x{\left(t \right)} + k x{\left(t \right)} + m \frac{d^{2}}{d t^{2}} x{\left(t \right)} = F{\left(t \right)}
  269. $$
  270. **Assistant**: (Internal tool call) `introduce_function` to define F(t):
  271. ```json
  272. {
  273. "func_name": "F"
  274. }
  275. ```
  276. **Assistant**: (Internal tool call) `dsolve_ode` to solve the differential equation:
  277. ```json
  278. {
  279. "expr_key": "expr_12",
  280. "func_name": "x"
  281. }
  282. ```
  283. Result:
  284. $$
  285. x{\left(t \right)} = C_{1} e^{\frac{t \left(- c + \sqrt{c^{2} - 4 k m}\right)}{2 m}} + C_{2} e^{- \frac{t \left(c + \sqrt{c^{2} - 4 k m}\right)}{2 m}} + \cdots
  286. $$
  287. ## Example Interaction 2: General Relativity
  288. **User**: Compute the trace of the Ricci tensor $R_{\mu\nu}$ using the inverse metric $g^{\mu\nu}$ for Anti-de Sitter spacetime to determine its constant scalar curvature $R$.
  289. **Assistant**: (Internal tool call) `create_predefined_metric` to create the Anti-de Sitter metric:
  290. ```json
  291. {
  292. "metric_name": "AntiDeSitter"
  293. }
  294. ```
  295. **Assistant**: (Internal tool call) `calculate_tensor` to calculate the Ricci tensor:
  296. ```json
  297. {
  298. "metric_key": "metric_AntiDeSitter",
  299. "tensor_type": "RICCI_TENSOR",
  300. "simplify_result": true
  301. }
  302. ```
  303. **Assistant**: (Internal tool call) `print_latex_tensor` to display the Ricci tensor:
  304. ```json
  305. {
  306. "tensor_key": "riccitensor_metric_AntiDeSitter"
  307. }
  308. ```
  309. Result:
  310. $$
  311. \left[\begin{matrix}3 & 0 & 0 & 0\\\\0 & - 3 \cos^{2}{\left(t \right)} & 0 & 0\\\\0 & 0 & - 3 \cos^{2}{\left(t \right)} \sinh^{2}{\left(\chi \right)} & 0\\\\0 & 0 & 0 & - 3 \sin^{2}{\left(\theta \right)} \cos^{2}{\left(t \right)} \sinh^{2}{\left(\chi \right)}\end{matrix}\right]
  312. $$
  313. **Assistant**: (Internal tool call) `calculate_tensor` to calculate the Ricci scalar:
  314. ```json
  315. {
  316. "metric_key": "metric_AntiDeSitter",
  317. "tensor_type": "RICCI_SCALAR",
  318. "simplify_result": true
  319. }
  320. ```
  321. **Assistant**: (Internal tool call) `print_latex_tensor` to display the Ricci scalar:
  322. ```json
  323. {
  324. "tensor_key": "ricciscalar_metric_AntiDeSitter"
  325. }
  326. ```
  327. Result:
  328. $$
  329. -12
  330. $$
  331. ## Example Interaction 3: Coupled ODE System (Fluid Dynamics)
  332. This example demonstrates solving a coupled system of ODEs and verifying the solution against an algebraic steady-state analysis, a task where LLMs typically hallucinate without a CAS to ground each step.
  333. **User**:
  334. > Use the sympy-mcp tools to solve this symbolically. Do not compute by hand.
  335. >
  336. > Two cylindrical tanks are connected by a pipe. Tank 1 has cross-sectional area A₁ = 2 m² and receives a constant inflow of Q = 0.5 m³/s. Water drains from Tank 1 into Tank 2 through a pipe with flow rate proportional to the height difference: q₁₂ = k·(h₁ - h₂) where k = 0.3 m²/s. Tank 2 has cross-sectional area A₂ = 1 m² and drains to the outside at rate q₂ = k·h₂ with the same k.
  337. >
  338. > Set up and solve the coupled system of ODEs for the water heights h₁(t) and h₂(t), starting from empty tanks (h₁(0) = 0, h₂(0) = 0). Then find the steady-state heights as t → ∞ by solving the equilibrium equations algebraically, and verify they match the long-term solution of the ODEs.
  339. **Assistant**: (Internal tool chain)
  340. 1. `intro_many`: introduce `t`, `k`, `A1`, `A2`, `Q` with real/positive assumptions
  341. 2. `introduce_function` × 2: introduce `h1(t)` and `h2(t)` as unknown functions
  342. 3. `introduce_expression` × 2: encode the mass-balance ODEs:
  343. $$A_1 \frac{dh_1}{dt} = Q - k(h_1 - h_2), \quad A_2 \frac{dh_2}{dt} = k(h_1 - h_2) - k h_2$$
  344. 4. `substitute_expression`: substitute numeric values for `k`, `A1`, `A2`, `Q`
  345. 5. `dsolve_ode` × 2: solve the coupled system; apply initial conditions via `substitute_expression`
  346. 6. `introduce_expression` × 2: encode equilibrium equations (derivatives set to zero)
  347. 7. `solve_linear_system`: solve the 2×2 algebraic system for `h1*`, `h2*`
  348. 8. `print_latex_expression`: display both the time-domain solution and the steady-state values
  349. ## Security Disclaimer
  350. This server runs on your computer and gives the language model access to run Python logic. Notably it uses Sympy's `parse_expr` to parse mathematical expressions, which is uses `eval` under the hood, effectively allowing arbitrary code execution. By running the server, you are trusting the code that Claude generates. Running in the Docker image is slightly safer, but it's still a good idea to review the code before running it.
  351. ## License
  352. Copyright 2025 Stephen Diehl.
  353. This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.