Mathematica MCP 服务器

Mathematica MCP Server

This project implements a Model Context Protocol server that mirrors the WLJS Notebook API exposed by a Wolfram Language runtime. The HTTP surface is documented in openapi.yaml; the Python layer focuses on MCP transport, tool orchestration, and error translation. The code is built with FastMCP and managed by uv for reproducible tooling.

Features

• Complete WLJS tool surface: readiness checks, notebook + cell management (including add_cells_batch), kernel lifecycle, transaction orchestration, extension discovery, and Wolfram Alpha proxying
• Structured MCP results wrap scalar responses (ids, booleans, status messages) into predictable dictionaries for downstream agents
• HTTP error handling maps WLJS failures to deterministic MCP error codes while preserving server-provided details
• Reusable check_health helper verifies the WLJS bridge before expensive work begins
• Embedded external/wljs-api submodule tracks the upstream REST reference used to generate our OpenAPI contract

Prerequisites

• Python managed via uv (see pyproject.toml for the pinned toolchain)
• A local Mathematica kernel (or WLJS bridge) hosting the endpoints documented in openapi.yaml, typically listening on http://127.0.0.1:20560

Setup

git submodule update --init --recursive
uv sync --extra dev

Running the Server

The server defaults to the stdio transport which works well for local MCP clients:

uv run python -m mathematica_mcp

Following the FastMCP quickstart pattern you can also run via the CLI:

uv run fastmcp run src/mathematica_mcp/server.py:mcp

To expose the HTTP transport instead of stdio:

uv run fastmcp run src/mathematica_mcp/server.py:mcp --transport http --port 8000

Claude Desktop Integration

Claude Desktop can load this server over the STDIO transport. Follow the FastMCP Claude Desktop guide and adapt the commands below to point at your local checkout.

1. Make sure the FastMCP CLI is available (pip install fastmcp or uv tool install fastmcp).

2. From the project root, install the server into Claude Desktop:

   复制

   fastmcp install claude-desktop src/mathematica_mcp/server.py:mcp \
     --with fastmcp \
     --with httpx \
     --with pydantic-settings
   

   The --with flags ensure Claude Desktop creates an isolated environment with the packages the server needs. Add more dependencies if you extend the project.

3. Restart Claude Desktop completely. A hammer icon (🔨) in the composer indicates the MCP tools loaded successfully.

4. Open a chat with Claude and run a test call (e.g. ready or list_notebooks) to verify the connection.

Tip: you can instead maintain a fastmcp.json file alongside this project and pass it to fastmcp install claude-desktop fastmcp.json for declarative dependency and environment management.

If the Mathematica HTTP bridge is not listening on the default http://127.0.0.1:20560, set the MATHEMATICA_MCP_BASE_URL environment variable in Claude Desktop's MCP configuration. The server derives every endpoint from this base URL.

Notebook Content Tips

• WLJS detects cell formats from the first line. Prefix the content with markers such as .md, .latex, or .mermaid (for example, .md\n# Heading) to switch renderers.
• Cells without a prefix are interpreted as Wolfram Language code.
• Cell evaluation is asynchronous; poll list_cells after evaluate_cell, add_cell, or add_cells_batch to observe WLJS-assigned identifiers and generated output.

Configuration

Environment variables prefixed with MATHEMATICA_MCP_ allow for runtime customization:

Development Notes

• See mathematica-mcp-spec.md for the implementation specification.
• TODO.md tracks outstanding work items and planned enhancements.
• AGENT.md documents the Codex agent context for this repository.

Testing

The test suite relies on mocked httpx.AsyncClient interactions to exercise the MCP tools deterministically, ensuring every WLJS endpoint is mapped and error handling is covered.

# run the full suite
uv run --extra dev pytest

# run only a specific test
uv run --extra dev pytest tests/test_mathematica_mcp.py::test_ready_tool_success

# include live WLJS integration tests (requires server at MATHEMATICA_MCP_BASE_URL)
uv run --extra dev pytest -m real_server