Skip to content
Power-AgentPublic

About

PowerMCP is an open-source collection of MCP servers for power system software like PowerWorld, PSSE and OpenDSS. These tools enable LLMs to directly interact with power system applications, facilitating intelligent coordination, simulation, and control in the energy domain.

Resources

Stars

238 stars

Watchers

7 watching

Forks

Repository files navigation

PowerMCP ⚡

PyPI License: MIT Python Version

PowerMCP is an open-source collection of MCP servers for power system software such as PSS/E, PowerWorld, PowerFactory, PSLF, PSCAD, OpenDSS, pandapower, and PyPSA. These tools enable LLMs to directly interact with power system applications, facilitating intelligent coordination, simulation, and control in the energy domain.

PowerMCP is part of PowerAgent, an open-source community for agentic AI in power systems, maintained by the Power and AI Initiative (PAI) at Harvard SEAS.

Install with your AI agent: paste this prompt into Claude Code, Codex, or another coding agent and it will install and configure PowerMCP for you.

🌟 What is MCP?

The Model Context Protocol (MCP) is a revolutionary standard that enables AI applications to seamlessly connect with various external tools. Think of MCP as a universal adapter for AI applications, similar to what USB-C is for physical devices. It provides:

  • Standardized connections to power system software and data sources
  • Secure and efficient data exchange between AI agents and power systems
  • Reusable components for building intelligent power system applications
  • Interoperability between different AI models and power system tools

🤝 Our Community Vision

We're building an open-source community focused on accelerating AI adoption in the power domain through MCP. Our goals are:

  • Collaboration: Bring together power system experts, AI researchers, and software developers
  • Innovation: Create and share MCP servers for various power system software and tools
  • Education: Provide resources and examples for implementing AI in power systems
  • Standardization: Develop best practices for AI integration in the energy sector

🚀 Getting Started with MCP

📖 Quick start

🚀 New to PowerMCP? Start here!

The recommended way to get started is the powermcp package and its installer. Either let an AI coding agent do it (copy the prompt), or run it yourself (see the Installation section below):

pip install powermcp
powermcp install        # pick tools, capture local paths, write your MCP client config

📋 The PowerMCP Tutorial PDF documents the original low-code / manual setup — cloning the repo and hand-editing the Claude Desktop config. It predates the powermcp installer and is not the recommended path; use it only if you specifically want the manual approach.

Video Demos

Check out these demos showcasing PowerMCP in action:

  • PowerMCP New Feature Release: pip install, automatic setup with powermcp install, and PowerIO integration.

  • Grid Impact Evaluation Demo: Agentic AI streamlines the grid impact evaluation of large loads such as data centers, automating the analysis and report generation.

  • PowerSkills + PowerMCP Demo: PowerSkills and PowerMCP together give AI agents the domain knowledge and structured instructions for simulation, analysis, and optimization across industry software tools, with reports in an industry-standard format.

  • Contingency Evaluation Demo: An LLM automatically operates power system software, such as PowerWorld and pandapower, to perform contingency analysis and generate professional reports.

  • Loadgrowth Evaluation Demo: An LLM automatically operates power system software, such as PowerWorld, to evaluate different load growth scenarios and generate professional reports with recommendations.

Useful MCP Tutorials

MCP follows a client-server architecture where:

  • Hosts are LLM applications (like Claude Desktop or IDEs) that initiate connections
  • Clients maintain 1:1 connections with servers, inside the host application
  • Servers provide context, tools, and prompts to clients

Check out these helpful tutorials to get started with MCP:

📦 Installation

🤖 Install with an AI agent (recommended)

More and more people install PowerMCP by asking an AI coding agent such as Claude Code, Codex, Cursor, or Cline to do it. Open the agent in a terminal on the machine where your power-system software lives, then paste this prompt and fill in the two lists:

Install and configure PowerMCP (https://github.com/Power-Agent/PowerMCP) on this computer.
Follow the agent guide step by step:
https://raw.githubusercontent.com/Power-Agent/PowerMCP/main/llms-install.md

Tools I want, in addition to the core pandapower, PyPSA and PowerIO: <for example OpenDSS, ANDES, PSS/E, or "core only">
MCP clients to configure: <for example Claude Code, Claude Desktop, Codex CLI>

Use a dedicated virtual environment. Ask me before guessing the install path of any
commercial software. Finish by running `powermcp doctor` and telling me what is left for me to do.

The agent follows llms-install.md: it checks your OS and Python, creates a virtual environment, installs the right extras, stores vendor software paths, writes the MCP client configuration without touching your other servers, and verifies the result. If your agent can't open web links, clone this repository and tell it to read llms-install.md from the clone.

After it finishes, restart your MCP client (start a new Claude Code or Codex session, or fully quit and reopen Claude Desktop) so it loads the new servers.

Install it yourself

PowerMCP installs as a single Python package with an interactive CLI. Python 3.10 through 3.14 is supported.

pip install powermcp

The base install includes the open-source engines that need no extra setup: pandapower, PyPSA, and PowerIO (the cross-server case-conversion substrate). Every other tool is opt-in via an extra. Quote the brackets, since zsh (the macOS default shell) otherwise rejects them:

pip install "powermcp[psse]"              # add PSS/E support
pip install "powermcp[andes,opendss]"     # add several tools at once
pip install "powermcp[opensource]"        # all open-source tools (ANDES, Egret, OpenDSS, surge, HOPE, LTSpice, GenX)
pip install "powermcp[windows]"           # all Windows vendor tools (PowerWorld, PSS/E, PSLF, PowerFactory, PSCAD)
pip install "powermcp[all]"               # everything (closed-source tools still need the local software)

Supported tools

Tool powermcp id pip extra Platform Notes
pandapower pandapower (core) any
PyPSA pypsa (core) any HiGHS included; CBC, GLPK, Gurobi optional
PowerIO powerio (core) any case parsing, conversion, and matrices for every other server
ANDES andes andes any
Egret egret egret any needs ipopt or Gurobi
OpenDSS opendss opendss any
surge surge surge any Python 3.12 to 3.14
HOPE hope hope any needs a HOPE.jl checkout and Julia
GenX genx genx any needs a GenX.jl checkout; SLURM to submit cases
LTSpice ltspice ltspice any LTspice must be installed (auto-detected)
PLEXOS database plexosdb plexosdb any Python 3.11 to 3.13; extra manual steps in PLEXOSDB/README.md
PowerWorld powerworld powerworld Windows needs a running, licensed Simulator
PSS/E psse psse Windows needs PSS/E installed
GE PSLF pslf pslf Windows needs PSLF installed
PowerFactory powerfactory powerfactory Windows needs PowerFactory installed
PSCAD pscad pscad-windows Windows needs PSCAD installed

Set up with the interactive installer

powermcp install

The wizard lets you pick tools (pandapower + PyPSA + PowerIO pre-selected), captures the local install path for any tools that need one (PSS/E, PSLF, PowerFactory, LTSpice, HOPE, GenX), installs the right extras, and writes the MCP client configuration for Claude Desktop, Claude Code, and the Codex CLI. Each entry launches the server with the absolute path of the Python interpreter that ran the installer, so keep that environment in place. Use --dry-run to preview the changes, --clients to pick which clients to configure, or --yes for a non-interactive core install.

In the interactive picker, move with ↑/↓ and press SPACE to toggle each tool before ENTER (ENTER alone keeps only the preselected tools). Prefer not to use the checkbox? Choose tools directly:

powermcp install --tools psse,andes      # core + the listed tools
powermcp install --all                   # every tool available on this platform

Re-running powermcp install interactively pre-checks the tools you've already installed or configured, so it preserves and updates your setup instead of resetting to the core tools. With --tools, list every tool you want to keep: powermcp_* entries for tools left out of the list are removed. Paths for tools like LTSpice are auto-detected and pre-filled, so you can usually just press Enter.

CLI commands

Command Description
powermcp install Setup wizard: interactive, or --tools <ids> / --all (also --dry-run, --yes, --clients claude-desktop,claude-code,codex,none)
powermcp run <tool> Launch a server over stdio (used by the generated client config)
powermcp list List the available tools, extras, and Windows-only flags
powermcp doctor [tool] Check dependencies and configured paths for every tool, or for one
powermcp config show / config set <tool>.<key> <path> Inspect / set local software paths
powermcp --version Print the installed version

Closed-source / EXE-based tools

These tools wrap commercial or locally-installed software, so PowerMCP stores the local path in ~/.powermcp/config.toml (captured by powermcp install, or set manually with powermcp config set):

Tool Config keys Example
PSS/E psse.python_lib, psse.bin, optional psse.bus_size powermcp config set psse.python_lib "C:\Program Files\PTI\PSSE36\36.2\PSSPY311". The engine starts at the bus size set in the PSS/E GUI; for a larger case, powermcp config set psse.bus_size 150000
PSLF pslf.python_lib powermcp config set pslf.python_lib "C:\Program Files\GE PSLF\PSLF_PYTHON"
PowerFactory powerfactory.python_path powermcp config set powerfactory.python_path "...\DIgSILENT\PowerFactory 2024\Python\3.11"
LTSpice ltspice.exe (auto-detected) Found automatically in standard locations — usually no setup needed. Override: powermcp config set ltspice.exe "C:\Program Files\ADI\LTspice\LTspice.exe"
HOPE hope.repo_root, hope.julia_bin, hope.julia_depot_path powermcp config set hope.repo_root "C:\src\HOPE"
GenX genx.repo_root powermcp config set genx.repo_root "/home/me/GenX.jl" — the GenX.jl checkout; GENX_DIR overrides it
PowerWorld (none) esa auto-discovers a running, licensed Simulator via COM; the powerworld extra also installs numba (required by esa)
PSCAD (none) pip install "powermcp[pscad-windows]" provides mhi-pscad; PSCAD must be installed
PLEXOS database (none) The upstream plexosdb-mcp package is not on PyPI yet; install it as described in PLEXOSDB/README.md

The Codex Desktop app on Windows has been reported to overwrite ~/.codex/config.toml; the Codex CLI is unaffected. If you use both, re-run powermcp install after Desktop edits.

Case compilation between servers (PowerIO)

PowerIO IR is the exchange format of this repository. PowerMCP runs the server shipped in PowerIO 0.11.2 (powermcp run powerio is python -m powerio.mcp); that server parses every grid exchange format, emits every target, summarizes, diagnoses, normalizes, lowers multiconductor networks, and calculates matrices. Its parse tool returns serialized PowerIO IR generation 2 ("schema": "pio-ir", "version": 2), a typed module carrying the electrical value, its provenance and its diagnostics. Every other server here consumes that document: the pandapower, PyPSA, ANDES and Egret adapters turn it into their own model with PowerIO's writers. PowerMCP itself never re-parses, re-validates, or recomputes what PowerIO states; it routes a declared value to a consumer that accepts it and owns only the final step into one simulator.

parsed = parse(path="case9.raw")                     # powerio server
ir = parsed["powerio_ir"]
summarize(powerio_ir=ir)
calc_matrix(matrix="ptdf", powerio_ir=ir)            # rows and columns carry bus ids and branch identities
diagnostics(powerio_ir=ir)
import_case_from_json(powerio_ir=ir, output_path="case9.nc")  # PyPSA
load_network_from_json(powerio_ir=ir)                         # pandapower
load_model_from_json(powerio_ir=ir)                           # Egret
load_network_from_json(powerio_ir=ir, out_path="case9.m")     # ANDES
emit(format="psse", destination="case9.raw", powerio_ir=ir)

powerio_ir is the argument every adapter takes; network_json remains an alias for the same document. A ScenarioSet requires scenario_id; a TimeSeries requires time_index; nested collections require both. An operating point entry reaches the solver as the network it states. The operating_point argument remains an alias for time_index.

import_case_from_json(
    powerio_ir=ir, output_path="dispatch.nc",
    scenario_id="high-demand", time_index=3,
)

Every adapter response carries the same tail: value_type (the PowerIO structural type that was selected), selection, diagnostics (full PowerIO records with code, severity, target, spans and suggested action) and warnings. The powerio adapters add the emission fidelity (exact_same_format when PowerIO echoed retained source bytes, canonical for fresh output) and the typed edits report described below, because they own the conversion into their own model. The package key keeps the IR context earlier clients read.

Typed edits before a solver import

The powerio adapters accept edits, a JSON list of what-if changes PowerIO applies as typed updates before the conversion. The whole list is validated first, then applied in list order; consecutive updates of one class apply as one atomic batch, and a bus load reallocation sees the values produced by the edits before it. The response reports the changed components, in application order, under edits.

op keys
set_load_active_power load, mw, terminal?
set_load_reactive_power load, mvar, terminal?
set_generator_active_power generator, mw, terminal?
set_generator_reactive_power generator, mvar, terminal?
set_generator_voltage_magnitude generator, vm_pu
set_generator_in_service generator, in_service
set_branch_in_service branch, in_service
set_transformer_tap_ratio transformer, tap_ratio
set_transformer_phase_shift transformer, shift_degrees
set_switch_closed switch, closed
set_branch_thermal_rating branch, mva, terminal?
set_bus_load_active_power bus, mw, allocation (proportional_to_current_active_power or equal)

Component ids are the stable identities PowerIO reports (loads:0, branches:3, or the source uid). A bus demand edit names an allocation rule because PowerIO never assigns aggregate demand to an arbitrary load.

load_network_from_json(
    powerio_ir=ir,
    edits='[{"op": "set_load_active_power", "load": "loads:0", "mw": 91.5},'
          ' {"op": "set_branch_in_service", "branch": "branches:3", "in_service": false}]',
)

Distribution networks

A multiconductor value is rejected by a balanced solver until the caller asks for the transformation: pass to_balanced=True (and base_mva) and the response carries PowerIO's readiness report under lowering, or call the powerio server's to_balanced_report and to_balanced tools first. Retaining a component does not establish that the selected solver models it. Use emit for a backend that needs files: OpenDSS output is a directory bundle whose master DSS artifact compile_opendss_file accepts; bmopf-json@0.1.0 and bmopf-json@0.2.0 select the BMOPF schema version (the latter writes draft BMOPF 0.2, subject to Task Force approval); geo-json writes a geographic layer.

The retired Package, model-json, package_json and package study_commit formats require migration: re-parse the original case and pass its powerio_ir.

PowerIO MCP paths support local files and file:// URIs. Set POWERIO_MCP_ALLOWED_ROOTS to an os.pathsep separated directory list to constrain the shared path policy. With no root variable set, paths stay beneath the directory the server process started in, which is rarely the directory an operator means. Legacy single-root environment aliases remain supported. Directory inputs check every descendant, and generated directories install from private sibling staging paths. Place POWERMCP_HOME under an allowed root for solver run artifacts. These checks cannot prevent another process from replacing a path after validation.

Running from a clone (without installing)

Every bundled server is still a standalone script. Clone the repo and run any server directly for use in Claude Desktop:

python pandapower/panda_mcp.py
python PSSE/psse_mcp.py          # uses ~/.powermcp/config.toml if present, else legacy default paths
python -m powerio.mcp            # powerio ships its own server; the clone holds no copy

Testing with your LLMs

Note: All MCPs should be tested via an MCP client (Claude Desktop, Claude Code, or Codex) before submitting a PR to ensure consistency.

powermcp install writes the client configuration for you. Each generated entry runs <python> -m powermcp run <tool> with the absolute interpreter path, because GUI clients such as Claude Desktop don't inherit your shell PATH. config.json shows the shorter form that works when powermcp is on PATH. For clients the installer doesn't write (Cursor, VS Code, and others), add the same command and arguments by hand; llms-install.md has an example. (The PowerMCP Tutorial PDF covers the older manual / low-code setup and isn't needed for the package install.)

📚 Documentation

For detailed documentation about MCP, please visit:

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details, and join the conversation in the PowerAgent Slack community.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Core Team

PowerAgent leads: Qian Zhang (student lead) and Le Xie (faculty lead)

PowerMCP: Qian Zhang, Steven Black, Paulo Radatz, Andrea Pomarico, Muhy Eddin Za'ter, Luan Lopes dos Santos, Stephen Jenkins, Maanas Goel, Shen Wang, Drew Gray, Samuel Talkington, Laura Hwa, Leo Winiecki, Brian Horakh, Aswin Krishna Poyil, Burhan Abdullah

The full PowerAgent team, including PowerFM, PowerSkills, PowerWF, and the PowerAgent Platform, is listed at poweragent.seas.harvard.edu.

Special Thanks

  • All contributors who help make this project better
  • The Power and AI Initiative (PAI) at Harvard SEAS
  • PowerFactory development and validation contributions by Aswin Krishna Poyil at the Institute of Electrical Energy Systems, Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU), with supervision and support from Tobias Lorz and Timon Conrad, who provided the opportunity to pursue this work independently

About

PowerMCP is an open-source collection of MCP servers for power system software like PowerWorld, PSSE and OpenDSS. These tools enable LLMs to directly interact with power system applications, facilitating intelligent coordination, simulation, and control in the energy domain.

Resources

Stars

238 stars

Watchers

7 watching

Forks

Releases

Packages

Contributors

Languages