README - PyPSA MCP: Energy Modeling for LLMs by cdgaete

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.

Demo Example

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.

https://github.com/user-attachments/assets/5633a431-7c3b-4a2f-9a9e-395dcbbb2e29

Demo Prompt

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

Overview

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

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

Features

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

Installation

Prerequisites

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

Main Installation (PyPI)

# Install from PyPI
pip install pypsamcp

# Or using uv (recommended)
uv pip install pypsamcp

Running PyPSA MCP

# Run using the installed package
pypsamcp

Configuring in Claude Desktop

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

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"
    ]
  }
}

Save the configuration file and restart Claude Desktop

Development Installation (from GitHub)

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]"

Running in Development Mode

# Run the server directly
python -m pypsamcp.server

Available Tools

The server provides the following MCP tools:

Model Management

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
)

Component Creation

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
)

Data and Simulation

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"
)

Example Prompts

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.

License

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

Acknowledgments

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