pypsa-mcp

PyPSA MCP is a Model Context Protocol (MCP) server for creating, analyzing, and optimizing energy system models using PyPSA (Python for Power System Analysis).

A Model Context Protocol (MCP) server that enables Large Language Models (LLMs) like Claude to interact with PyPSA for energy model creation and analysis via natural language.

Below is a demo video showing how to use PyPSA MCP with Claude. The video demonstrates creating a simple two-bus model, running power flow calculations, and performing optimization.

You can try this exact prompt with Claude to reproduce the example shown in the video:

I'd like to build an energy system model and perform optimization using PyPSA. Please help me with these steps: 
1. Create a simple two-bus model with: 
   1. Two buses at (0,0) and (100,0) with 220 kV nominal voltage 
   2. A generator at bus1 with 100 MW capacity and 50 €/MWh cost 
   3. A load at bus2 with 80 MW demand
   4. 24 hourly snapshots for January 1, 2025
2. Run a power flow calculation to verify the model 
3. Perform optimization with the highs solver using the kirchhoff formulation 
4. Discuss the results

PyPSA MCP provides a bridge between Large Language Models and PyPSA, allowing you to:

1. Create and manage energy system models through natural language
2. Add network components like buses, generators, and transmission lines
3. Set up time series data for simulation
4. Run power flow and optimization calculations
5. Analyze results

• Model Management

  • Create new PyPSA energy models
  • List and select from available models
  • Export detailed model summaries
  • Delete models when no longer needed

• Component Creation

  • Add buses, generators, loads, and other network components
  • Configure component parameters through natural language
  • Modify existing components
  • Organize components into meaningful groups

• Data and Simulation

  • Set time snapshots for simulation periods
  • Add time series data for loads and generators
  • Run power flow calculations
  • Perform optimization with various solvers and formulations

• Results Analysis

  • Extract key metrics from simulation results
  • Generate summaries of model performance
  • Export data for further analysis

• Python 3.10 or higher
• uv (recommended for easy dependency management)

# Install from PyPI
pip install pypsamcp

# Or using uv (recommended)
uv pip install pypsamcp

# Run using the installed package
pypsamcp

1. Locate Claude Desktop's configuration file (typically in ~/.config/Claude/config.json)

2. Add PyPSA MCP to the mcpServers section:

   "mcpServers": {
     "PyPSA MCP":{
       "command": "uv",  # Sometimes /path/to/local/uv (remove this comment)
       "args": [
         "run",
         "--with",
         "pypsamcp",
         "pypsamcp"
       ]
     }
   }

3. Save the configuration file and restart Claude Desktop

For contributors or users who want to modify the code:

# Clone the repository
git clone https://github.com/cdgaete/pypsa-mcp.git
cd pypsa-mcp

# Install development dependencies with uv
uv pip install -e ".[dev]"

# Run the server directly
python -m pypsamcp.server

The server provides the following MCP tools:

create_energy_model(
    id: str,
    name: str = None,
    description: str = None
)

list_models()

delete_model(
    id: str
)

export_model_summary(
    id: str,
    include_components: bool = True,
    include_parameters: bool = True
)

add_bus(
    model_id: str,
    name: str,
    v_nom: float,
    x: float = 0.0,
    y: float = 0.0,
    carrier: str = "AC"
)

add_generator(
    model_id: str,
    name: str,
    bus: str,
    p_nom: float,
    marginal_cost: float = 0.0,
    carrier: str = "generator"
)

add_load(
    model_id: str,
    name: str,
    bus: str,
    p_set: float
)

add_line(
    model_id: str,
    name: str,
    bus0: str,
    bus1: str,
    x: float,
    r: float = 0.0,
    g: float = 0.0,
    b: float = 0.0,
    s_nom: float = 0.0
)

add_storage(
    model_id: str,
    name: str,
    bus: str,
    p_nom: float,
    max_hours: float,
    efficiency_store: float = 1.0,
    efficiency_dispatch: float = 1.0,
    standing_loss: float = 0.0
)

set_snapshots(
    model_id: str,
    start_time: str,
    end_time: str,
    freq: str = "H"
)

run_powerflow(
    model_id: str,
    snapshot: str = None
)

run_optimization(
    model_id: str,
    solver_name: str = "glpk",
    formulation: str = "kirchhoff"
)

Here are some examples of how to use PyPSA MCP with Claude:

Create a new energy system model with three buses, two generators, and a load.

Add a wind generator with 100 MW capacity to bus "bus1" with a marginal cost of 10.

Run a power flow calculation on the current model and show me the results.

Optimize the model using the GLPK solver and summarize the key findings.

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

• Built on PyPSA for power system modeling
• Uses FastMCP for the Model Context Protocol implementation
• Inspired by the need to make energy system modeling more accessible through natural language interfaces