preCICE AI MCP Server

A Model Context Protocol (MCP) server for exploring and operating local preCICE simulation projects from AI coding tools such as Codex, Claude Code, Cursor, Windsurf, and Claude Desktop.

Exposes 26 tools covering project discovery, config inspection, precice-cli wrapping (version, config check/format/doc/init, profiling), command execution, log analysis, and a semantic knowledge base built from the preCICE documentation using vector embeddings.

This README is the end-user guide: install it, register it with your MCP client, and start using the tools. If you want the architecture, file-by-file walkthrough, local development notes, or contribution workflow, read CONTRIBUTOR_GUIDE.md.

What It Does

• Exposes MCP tools for project discovery, config inspection, log reading, and safe command execution.
• Wraps selected precice-cli functionality for validation, initialization, and profiling tasks.
• Provides a semantic preCICE knowledge base backed by pre-built embeddings downloaded from GitHub Releases.
• Ships a precice-ai CLI that sets up supported MCP clients for you.

Installation

From PyPI (recommended)

pipx install precice-ai

pipx installs precice-ai into its own isolated environment and - critically on Windows - takes care of putting its Scripts folder on PATH for you (pipx ensurepath, then open a new terminal).

Plain pip install precice-ai also works, but on Windows especially, a global (non-venv) pip install often places precice-ai.exe in a Scripts folder that isn't on PATH yet, so the freshly installed precice-ai command isn't recognized even though the install itself succeeded. If that happens:

• Look for a pip warning line during install like The script precice-ai.exe is installed in '...\Scripts' which is not on PATH and add that folder to PATH (or re-run with pipx instead, which does this automatically).
• Or, as an immediate workaround that doesn't need PATH changes at all, run python -m precice_ai.cli.main in place of precice-ai.

From source (for development)

macOS / Linux:

git clone https://github.com/vaibhavd2103/precice-ai
cd precice-ai
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Windows PowerShell:

git clone https://github.com/vaibhavd2103/precice-ai
cd precice-ai
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .

One-command bootstrap helper

If you want the repo to create a virtual environment and immediately run the bootstrap flow:

./install.sh auto --projects-dir /path/to/preCICE/cases

After installation, the precice-ai command is available inside the virtual environment.

Quick Start

Register the server with a supported MCP client:

precice-ai bootstrap auto --projects-dir /path/to/preCICE/cases

Semantic KB queries embed the question through an OpenAI-compatible embeddings API, so you need an API key — pass one at bootstrap:

precice-ai bootstrap codex \
  --projects-dir /path/to/preCICE/cases \
  --openrouter-api-key sk-or-...

Use --blablador-api-key ... instead for Blablador. Keyword search (kb_query_precice_lexical) needs no key.

This command:

• creates or updates .env
• injects runtime variables into the MCP client config
• registers python -m precice_ai.server as the MCP server command

Registering the server only makes its tools available — it doesn't tell the client to actually use them for preCICE questions in every project on this machine (that's normally what a project's own CLAUDE.md/AGENTS.md does, but those are scoped to one project directory). To get the same "always use precice-ai for preCICE questions" behavior globally, add --write-global-instructions:

precice-ai bootstrap claude-code --write-global-instructions

This appends a steering snippet to the platform's global instructions file (~/.claude/CLAUDE.md for Claude Code, ~/.codex/AGENTS.md for Codex) — idempotent, safe to run repeatedly. For platforms without a known global instructions file (Claude Desktop, Cursor, Windsurf, generic), the same snippet is printed instead so you can add it yourself.

List which supported clients are detected locally:

precice-ai list-platforms

Supported Clients

• auto
• claude-code
• claude-desktop
• codex
• cursor
• windsurf
• generic

generic prints config snippets for manual installation instead of editing a specific client config automatically.

Manual MCP Setup

If you do not want to use precice-ai bootstrap, configure your client manually.

Use the Python interpreter inside the virtual environment:

• macOS / Linux: .venv/bin/python
• Windows: .venv\Scripts\python.exe

Use this server command:

-m precice_ai.server

JSON-based clients

Use this structure for Claude Code project config, Claude Desktop, Cursor JSON config, Windsurf, or any other JSON-based MCP client:

{
  "mcpServers": {
    "precice-ai": {
      "command": "/absolute/path/to/precice-ai/.venv/bin/python",
      "args": ["-m", "precice_ai.server"],
      "env": {
        "PRECICE_PROJECTS_DIR": "/absolute/path/to/preCICE/cases"
      }
    }
  }
}

Add "OPENROUTER_API_KEY": "sk-or-..." (or "BLABLADOR_API_KEY": "...") to env — semantic KB queries embed the question through an embeddings API and need a key.

Claude Code project scope (.mcp.json)

For Claude Code specifically, a portable, checked-in template lives at .mcp.json.example — copy it to .mcp.json (or run precice-ai bootstrap claude-code, which writes the same thing):

{
  "mcpServers": {
    "precice-ai": {
      "command": "${PRECICE_AI_PYTHON:-.venv/bin/python}",
      "args": ["-m", "precice_ai.server"],
      "env": {
        "PRECICE_PROJECTS_DIR": "${PRECICE_PROJECTS_DIR:-test-projects}"
      }
    }
  }
}

Claude Code launches the server with the repo root as the working directory and expands ${VAR:-default}, so this works as-is after install.sh / install.ps1 on any OS. Overrides, only if the defaults don't fit your setup:

• PRECICE_AI_PYTHON — path to the interpreter (e.g. .venv\Scripts\python.exe if a client doesn't pick the POSIX path on Windows, or an absolute path to a global install).
• PRECICE_PROJECTS_DIR — directory holding your preCICE cases.

.mcp.json itself is git-ignored so a regenerated copy (or an injected API key) is never committed.

Codex

Native CLI:

codex mcp add precice-ai \
  --env PRECICE_PROJECTS_DIR=/absolute/path/to/preCICE/cases \
  -- /absolute/path/to/precice-ai/.venv/bin/python -m precice_ai.server

Direct ~/.codex/config.toml form:

[mcp_servers."precice-ai"]
command = "/absolute/path/to/precice-ai/.venv/bin/python"
args = ["-m", "precice_ai.server"]

[mcp_servers."precice-ai".env]
PRECICE_PROJECTS_DIR = "/absolute/path/to/preCICE/cases"

Add OPENROUTER_API_KEY (or BLABLADOR_API_KEY) here — semantic KB queries embed the question through an embeddings API and need a key.

Common config locations

• Claude Code project scope: .mcp.json
• Claude Code user scope: ~/.claude/settings.json
• Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json
• Claude Desktop Linux: ~/.config/Claude/claude_desktop_config.json
• Cursor global scope: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Codex: ~/.codex/config.toml

Restart or reload the client after editing its config.

Environment Variables

Semantic KB queries embed the question through an OpenAI-compatible embeddings API, so OPENROUTER_API_KEY or BLABLADOR_API_KEY must be set. The published KB is built with openai/text-embedding-3-small; the query model must match it (keep the EMBEDDING_MODEL default, or rebuild the KB).

Common variables:

To use Blablador, set BLABLADOR_API_KEY and a matching model/endpoint:

precice-ai bootstrap codex \
  --projects-dir /path/to/preCICE/cases \
  --blablador-api-key ... \
  --embedding-base-url https://helmholtz-blablador.fz-juelich.de:8000/v1 \
  --embedding-model alias-embeddings

Note: a model other than the KB's build model produces vectors of a different dimension, so you must also rebuild the KB (precice-ai kb ingest from a full clone, or the kb-ingest.yml Action) with the same model.

How To Use It

Once your MCP client sees the server, the main workflow is:

1. Ask the agent to list available preCICE projects.
2. Inspect the project structure and locate precice-config.xml.
3. Read or summarize the config.
4. Read logs or run safe read-only commands in the project.
5. Check KB freshness with kb_precice_status(), then use kb_query_precice(...) for fresh categories or kb_query_precice_live(...) to refresh stale/missing ones.

Typical tool calls:

list_precice_projects()
inspect_project_structure("partitioned-heat-conduction")
find_precice_config("partitioned-heat-conduction")
inspect_precice_config("partitioned-heat-conduction")
summarize_precice_config("partitioned-heat-conduction")
read_latest_log("partitioned-heat-conduction")
analyze_precice_logs("partitioned-heat-conduction")
kb_precice_status()
# If the documentation category is fresh:
kb_query_precice("how does implicit coupling work in preCICE?", category="documentation")
# If the documentation category is missing or stale:
kb_query_precice_live("how does implicit coupling work in preCICE?", category="documentation")

Safe command execution is available through:

run_command_in_project("partitioned-heat-conduction", "ls -la")
run_command_in_project("partitioned-heat-conduction", "cat run.sh")

Only allowlisted command prefixes are permitted.

precice-cli-Backed Tools

Some MCP tools wrap precice-cli. Those tools require precice-cli to be installed separately and available on PATH.

Examples:

precice_version()
precice_config_check("/absolute/path/to/project")
precice_config_visualize("/absolute/path/to/project")
precice_config_doc("/absolute/path/to/project", "participant")
precice_init(...)
precice_profiling_analyze("/absolute/path/to/project")

If precice-cli is missing, those tools return an install hint instead of crashing the server.

CLI Commands

The Typer-based CLI exposes:

• precice-ai setup <platform>
• precice-ai bootstrap [platform]
• precice-ai open [platform]
• precice-ai list-platforms
• precice-ai server
• precice-ai kb status
• precice-ai kb ingest
• precice-ai kb query

Examples:

precice-ai --help
precice-ai list-platforms
precice-ai kb status
precice-ai kb ingest
precice-ai kb query "implicit coupling" --mode vector-live
precice-ai server

Running The Server Manually

All of the following start the same MCP server:

precice-ai server
python -m precice_ai.server
python server.py

This is mostly useful for local debugging or manual client integration.

Knowledge Base Storage

precice-ai setup/bootstrap automatically download the full knowledge base (all 7 vector categories + the lexical index) the first time you run them, so it's ready to query immediately. This is a best-effort step — it never fails setup, even if GitHub is unreachable. Pass --skip-kb-ingest to skip it (e.g. in CI or offline environments), and run precice-ai kb ingest manually later.

Vector KB assets are stored outside the repo by default:

~/.precice-ai/kb_store/kb-embeddings-about.npz
~/.precice-ai/kb_store/kb-embeddings-community.npz
~/.precice-ai/kb_store/kb-embeddings-documentation.npz
~/.precice-ai/kb_store/kb-embeddings-tutorials.npz
~/.precice-ai/kb_store/kb-embeddings-forum.npz
~/.precice-ai/kb_store/kb-embeddings-issues.npz
~/.precice-ai/kb_store/kb-embeddings-pulls.npz

Check status:

precice-ai kb status

Or from MCP:

kb_precice_status()

Safety Notes

• run_command_in_project is intentionally restrictive and only allows approved command prefixes.
• The server blocks obviously destructive patterns such as rm, sudo, curl, wget, and shutdown commands.
• Log analysis is heuristic and meant to assist debugging, not replace solver-level validation.
• Document embeddings are prebuilt offline and shipped as a GitHub Release asset; at query time only the short question string is sent to the embeddings API. Keyword search (kb_query_precice_lexical) makes no external call at all.

Project Layout

For contributors, the deep walkthrough lives in CONTRIBUTOR_GUIDE.md. At a high level:

precice_ai/
  cli/      # user-facing Typer CLI and platform installers
  core/     # path resolution, safety checks, command runner, KB logic
  tools/    # MCP tool registration modules
  utils/    # JSON schema and supporting assets
scripts/    # KB build and maintenance scripts
server.py   # convenience entry point for local dev

License

MIT — see LICENSE.