PSCAD MCP for GitHub Copilot CLI

pscad-mcp is a Model Context Protocol (MCP) server that lets GitHub Copilot CLI control PSCAD through the mhi.pscad automation API.

The server is designed for Windows-based power-system workflows where you want Copilot to do more than explain code: it can connect to a live PSCAD session, open projects, edit parameters, build cases, run simulations, inspect outputs, and manipulate the canvas.

Why this repo exists

PSCAD automation is powerful, but the raw API is not especially friendly for conversational workflows. This project packages that API into structured MCP tools so Copilot CLI can:

• attach to an existing PSCAD session or launch one
• inspect projects, simulation status, and output messages
• update project settings and component parameters
• create, place, wire, move, and delete components on the canvas
• run builds, simulation sets, and output file reads
• read synced PSCAD API documentation when it needs extra context

Tool coverage

The server currently exposes tool groups for:

• application lifecycle and documentation access
• project loading, simulation control, and settings
• component search, parameter reads, and updates
• canvas creation and editing
• component transforms and port inspection
• simulation-set operations
• project creation, save, and build tasks
• simulation output capture and file parsing

The implementation is modular, with each tool family registered from its own module in pscad_mcp\tools.

Requirements

For full PSCAD automation you need:

• Windows
• Python 3.10+
• PSCAD installed
• the PSCAD Python packages, typically installed through the optional windows extras in this repo
• GitHub Copilot CLI

You can still run tests and documentation-related tasks without PSCAD installed.

Install GitHub Copilot CLI

Install Copilot CLI using one of the supported methods from GitHub. On Windows, the most direct option is:

winget install GitHub.Copilot

You can also install via npm:

npm install -g @github/copilot

Then start it with:

copilot

If needed, sign in from inside the CLI using /login.

Install this MCP server

From the repository root:

py -3 -m pip install -e ".[windows]"

If python is available on your machine, this is equivalent:

python -m pip install -e ".[windows]"

For non-Windows development tasks such as tests or documentation work, install base dependencies only:

py -3 -m pip install -e .

Quick setup for Copilot CLI

The easiest path is the included installer:

py -3 mcp_installer.py

It installs the package, tries to sync PSCAD documentation, and prints the values you should enter into Copilot CLI.

You can also configure the server manually.

Option 1: Add the server interactively in Copilot CLI

1. Start Copilot CLI in this repository:

   copilot
   

2. Run:

   /mcp add
   

3. Fill in the server details:

   • Name: pscad
   • Type: stdio
   • Command: your Python executable
   • Args: -m pscad_mcp.main

4. Press Ctrl+S to save.

By default, Copilot CLI stores MCP definitions in ~/.copilot/mcp-config.json on Windows as %USERPROFILE%\.copilot\mcp-config.json.

Option 2: Edit mcp-config.json directly

If you prefer editing the config file yourself, add an entry like this:

{
  "mcpServers": {
    "pscad": {
      "type": "stdio",
      "command": "C:\\Path\\To\\Python\\python.exe",
      "args": ["-m", "pscad_mcp.main"],
      "tools": ["*"]
    }
  }
}

Replace the command path with the interpreter from the environment where pscad-mcp is installed.

First prompts to try in Copilot CLI

Once the server is registered, open copilot in this repository and try prompts like:

• Connect to my local PSCAD instance and show me its status.
• List the projects currently loaded in PSCAD.
• Load C:\Projects\IEEE_9Bus.pscx and start the simulation.
• Find the component named MainTransformer and show its parameters.
• Read the PSCAD project documentation module and summarize the run_status API.
• Create a bus on the main canvas and connect it to the selected components.

Running the server directly

To launch the MCP server without the installer:

py -3 -m pscad_mcp.main

An installed entry point is also available:

pscad-mcp

Development workflow

Sync documentation snapshots

This project can generate PSCAD API reference snapshots that are easier for LLMs to consume:

py -3 -m pscad_mcp.utils.doc_manager

Generated files are written to:

• docs\raw for raw extracted output
• docs\md for enriched Markdown

Run tests

py -3 -m unittest discover tests

Tests mock the PSCAD layer, so they can run without PSCAD installed.

Project structure

pscad_mcp\
  core\
    connection_manager.py
    executor.py
  tools\
    app_tools.py
    project_tools.py
    data_tools.py
    simset_tools.py
    creation_tools.py
    canvas_tools.py
    component_tools.py
  utils\
    doc_manager.py
  main.py
tests\
docs\

Architecture notes

Two implementation details matter for reliability:

• PSCADConnectionManager tracks the live PSCAD handle and checks process health before reuse.
• RobustExecutor serializes PSCAD calls through a single-worker executor with a timeout guard to reduce hangs from COM/RMI operations.

Those guardrails are important because PSCAD automation is effectively single-threaded and can become unstable if calls are issued concurrently.

Troubleshooting

If Copilot CLI can see the server but tool calls fail:

• verify the configured Python executable matches the environment where pscad-mcp is installed
• confirm PSCAD is installed and licensed
• rerun py -3 mcp_installer.py
• run py -3 -m unittest discover tests to verify the Python package is still healthy

If documentation tools return no modules, run the documentation sync command again.

License

MIT