PyBaMM Server

This project exposes PyBaMM documentation and source code through a local MCP server so an LLM-enabled IDE can search docs and open files directly from tools.

What This Server Does

At startup, the project prepares three things:

1. A local clone of the PyBaMM repository (./PyBaMM)
2. Built plain-text docs (PyBaMM/docs/_build/text)
3. A full-text SQLite index (pybamm_docs.db)

Then server.py starts an MCP stdio server that provides these tools:

• search_pybamm_docs(query): full-text search across PyBaMM docs
• read_doc_page(filepath): read one docs text page from search results
• read_pybamm_source_code(module_path): open source files from the cloned repo

Prerequisites

Docker workflow

• Docker
• Docker Compose v2 (docker compose)

Local (non-Docker) workflow

• Python 3.11+
• Git
• make
• pandoc

Install And Run With Docker

From this repository root:

docker compose build
docker compose run --rm --no-deps -T pybamm-mcp

Notes:

• The first build can take a while because it builds PyBaMM docs.
• Transport is stdio (no HTTP/TCP port).
• Rebuild after changing Dockerfile, requirements.txt, build_index.py, or server.py:

docker compose build --no-cache

Install And Run Locally

From this repository root:

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
git clone --depth 1 --branch main https://github.com/pybamm-team/PyBaMM.git PyBaMM
pip install -e ./PyBaMM
make -C PyBaMM/docs text
python build_index.py
python server.py

Notes:

• server.py expects paths relative to this repo root. Run it from here.
• If PyBaMM/ already exists, skip the clone command.
• Rebuild docs/index after updating the PyBaMM checkout:

make -C PyBaMM/docs text
python build_index.py

Configure Your IDE MCP Client

Most MCP-enabled IDEs use a JSON server entry with:

• a command to run
• args
• optional cwd

Add one of the following entries in your IDE MCP settings.

Option A: Docker-backed server (recommended for consistency)

{
  "mcpServers": {
    "pybamm-docs": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/absolute/path/to/pybamm_mcp_server/docker-compose.yml",
        "run",
        "--rm",
        "--no-deps",
        "-T",
        "pybamm-mcp"
      ]
    }
  }
}

Option B: Local virtualenv server (fastest startup after setup)

{
  "mcpServers": {
    "pybamm-docs": {
      "command": "/absolute/path/to/pybamm_mcp_server/.venv/bin/python",
      "args": ["/absolute/path/to/pybamm_mcp_server/server.py"],
      "cwd": "/absolute/path/to/pybamm_mcp_server"
    }
  }
}

Option C: IDE running on Windows, server in WSL

If your IDE launches commands in Windows but your project is in WSL:

{
  "mcpServers": {
    "pybamm-docs": {
      "command": "wsl",
      "args": [
        "-e",
        "bash",
        "-lc",
        "cd /absolute/path/to/pybamm_mcp_server && .venv/bin/python server.py"
      ]
    }
  }
}

Verify IDE Connection

After adding the server config:

1. Restart your IDE MCP service (or the IDE itself).
2. Confirm pybamm-docs shows as connected.
3. Run a quick tool call, for example: search_pybamm_docs("single particle model").

If the server fails to start, most issues are one of:

• wrong absolute path in MCP config
• missing docs/index (make text and python build_index.py not run)
• wrong working directory (must be this repo root for local mode)