pfc-mcp

Name: PFC - ITASCA Discrete Element Simulation
Author: yusong652

MCP server that gives AI agents full access to ITASCA PFC - browse documentation, run simulations, capture plots, all through natural conversation.

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:

text

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:

json

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

2. Install dependency:

python

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

Start Bridge & Verify

python

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
`uvx` not found	Install uv or switch client MCP config to `command: "uv"` with `args: ["tool", "run", "pfc-mcp"]`
Bridge won't start	In PFC Python/IPython console, install/upgrade `pfc-mcp-bridge` with `import pip; pip.main(["install", "--user", "-U", "pfc-mcp-bridge"])`
Tasks not processing / cannot connect	If execution tools return `ok=false`, `error.code=bridge_unavailable`, and `error.details.reason=cannot connect to bridge service`, start bridge in PFC (`pfc_mcp_bridge.start()`) and ensure `PFC_MCP_BRIDGE_URL` matches the active bridge URL
`pfc_capture_plot` unsupported	Plot capture requires PFC GUI; console mode does not support it
Bridge on custom port	Set MCP server env `PFC_MCP_BRIDGE_URL=ws://localhost:<bridge-port>` (for example `ws://localhost:9002`)
Connection failed	Check bridge is running, target port is available, see `.pfc-bridge/bridge.log`

Development

bash

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

License

MIT - see LICENSE.

PFC - ITASCA Discrete Element Simulation