pfc-mcp

English | 简体中文

MCP server that gives AI agents full access to

Built on the Model Context Protocol, pfc-mcp turns any MCP-compatible AI client (Claude Code, Codex CLI, Gemini CLI, OpenCode, toyoura-nagisa, etc.) into a PFC co-pilot that can look up commands, execute scripts, monitor long-running simulations, and capture visualizations.

Tools (10)

Documentation (5) - no bridge required

• Browse PFC command tree, Python SDK reference, and reference docs (contact models, range elements)

• Search commands and Python APIs by keyword (BM25 ranked)

Execution (5) - requires bridge in a running PFC process

• Submit Python scripts and poll status/output in real time

• List and manage tasks across sessions

• Interrupt running simulations

• Capture PFC plot images with configurable camera, coloring, and cut planes

Quick Start

Prerequisites

• ITASCA PFC 7.0 installed (pfc2d700_gui.exe or pfc3d700_gui.exe)

• uv installed (for uvx)

Agentic Setup (Recommended)

Copy this to your AI agent and let it self-configure:

Fetch and follow this bootstrap guide end-to-end:
https://raw.githubusercontent.com/yusong652/pfc-mcp/main/docs/agentic/pfc-mcp-bootstrap.md

Manual Setup

1. Register the MCP server in your client config:

{
  "mcpServers": {
    "pfc-mcp": {
      "command": "uvx",
      "args": ["pfc-mcp"]
    }
  }
}

2. Install dependency:

import pip
pip.main(["install", "--user", "-U", "pfc-mcp-bridge"])

Start Bridge & Verify

import pfc_mcp_bridge
pfc_mcp_bridge.start()

Verify - reconnect your MCP client and ask the agent to call pfc_list_tasks to verify the full MCP + bridge connection.

Design Highlights

• Documentation as a boundary map - browse and search tools let agents discover what PFC can do, reducing hallucinated commands

• Task queue with live status - scripts are queued and executed sequentially; agents can poll output and status in real time

• Callback-based control - gracefully interrupt long-running cycle() calls, and capture plots mid-simulation without pausing it

Runtime Model

Documentation tools work standalone. Execution tools require a running bridge.

Troubleshooting

Development

uv sync --group dev    # Install with dev dependencies
uv run pytest          # Run tests
uv run pfc-mcp         # Run server locally

License

MIT - see LICENSE.