pfc-mcp is an MCP server that gives AI agents access to ITASCA PFC (Particle Flow Code) for browsing documentation, running simulations, and capturing visualizations through natural conversation.
Documentation Tools (no PFC installation required)
Browse PFC command tree (
pfc_browse_commands): Explore commands by category or get full docs for specific commands (e.g.,ball create)Browse Python SDK reference (
pfc_browse_python_api): Navigate the ITASCA Python API (e.g.,itasca.ball,itasca.ball.Ball.pos)Browse reference documentation (
pfc_browse_reference): Look up contact model properties, range element syntax, and other language elementsSearch PFC commands by keyword (
pfc_query_command): BM25-ranked keyword search across all PFC commandsSearch Python API by keyword (
pfc_query_python_api): BM25-ranked keyword search across the PFC Python SDK
Execution Tools (requires bridge running inside a live PFC process)
Submit scripts for execution (
pfc_execute_task): Asynchronously queue and run Python scripts inside a live PFC sessionMonitor task progress (
pfc_check_task_status): Poll real-time status and output with filtering and paginationList all tasks (
pfc_list_tasks): View tracked tasks across sessionsInterrupt running simulations (
pfc_interrupt_task): Gracefully stop long-runningcycle()calls mid-executionCapture plot images (
pfc_capture_plot): Screenshot PFC visualizations with configurable camera position, ball/wall/contact coloring, cut planes, zoom, and projection type
Works with any MCP-compatible client (Claude Code, Codex CLI, Gemini CLI, etc.). The documentation tools serve as a boundary map to reduce hallucinated commands by letting agents discover PFC capabilities directly.
pfc-mcp
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.exeorpfc3d700_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.mdManual 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
Component | PyPI | Python | Role |
pfc-mcp | >= 3.10 | MCP server (documentation + execution client) | |
pfc-mcp-bridge | >= 3.6 | WebSocket bridge inside PFC process (GUI or console) |
Documentation tools work standalone. Execution tools require a running bridge.
Troubleshooting
Symptom | Fix |
| Install uv or switch client MCP config to |
Bridge won't start | In PFC Python/IPython console, install/upgrade |
Tasks not processing / cannot connect | If execution tools return |
| Plot capture requires PFC GUI; console mode does not support it |
Bridge on custom port | Set MCP server env |
Connection failed | Check bridge is running, target port is available, see |
Development
uv sync --group dev # Install with dev dependencies
uv run pytest # Run tests
uv run pfc-mcp # Run server locallyLicense
MIT - see LICENSE.
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.