README.md

---
title: PowerMCP - Power System Analysis MCP Server
emoji: ⚡
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.1.0
app_file: app.py
pinned: false
license: mit
tags:
- mcp
- power-systems
- electrical-engineering
- simulation
- model-context-protocol
---

# ⚡ PowerMCP - Power System Analysis MCP Server

[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
[![Gradio](https://img.shields.io/badge/Gradio-5.0+-orange)](https://gradio.app/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

This is an **MCP-enabled Hugging Face Space** for **PowerMCP** - an open-source collection of Model Context Protocol (MCP) servers for power system software. This Space can be added as an MCP tool to Claude Desktop, Cursor, or any other MCP-compatible client with a single click!

## 🌟 What is PowerMCP?

PowerMCP enables Large Language Models (LLMs) to directly interact with power system applications through the Model Context Protocol. It bridges the gap between AI and power system analysis, facilitating:

- **Intelligent Power Flow Analysis**: Let AI perform complex power system simulations
- **Automated Contingency Analysis**: AI-driven evaluation of grid contingencies  
- **Dynamic Simulation**: Transient stability and time-domain analysis
- **Energy System Optimization**: Network expansion and optimal power flow
- **Professional Report Generation**: AI-generated analysis reports

## 🔧 Supported Power System Tools

### 🔌 pandapower
Python-based power system analysis focusing on power flow and contingency analysis.
- Create and manage power networks
- AC/DC power flow calculations
- N-1 and N-2 contingency analysis
- Network modification and optimization

### ⚡ PyPSA (Python for Power System Analysis)
Energy system optimization and network expansion planning.
- Multi-period optimization
- Unit commitment and economic dispatch
- Network expansion planning
- Renewable integration analysis

### 🌊 ANDES
Dynamic simulation and transient stability analysis.
- Time-domain simulation
- Transient stability analysis
- Small-signal stability
- Dynamic model library

## 🚀 Quick Start

### Option 1: Install from GitHub (Local MCP Server)

```bash
# Install PowerMCP
pip install git+https://github.com/Power-Agent/PowerMCP.git

# Configure Claude Desktop (macOS)
# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "pandapower": {
      "command": "powermcp-pandapower"
    }
  }
}

# Restart Claude Desktop and start using PowerMCP!
```

See [INSTALL.md](INSTALL.md) for detailed installation instructions.

### Option 2: Use Hugging Face Space as MCP Tool

1. **Install an MCP Client**:
   - [Claude Desktop](https://claude.ai/download)
   - [Cursor](https://cursor.sh/)
   - [Windsurf](https://codeium.com/windsurf)
   - VS Code with Cline extension

2. **Add PowerMCP to Your Client**:
   - Click the **MCP badge** on this Space
   - Select "Add to MCP tools"
   - Confirm when prompted
   - The tools will be available instantly in your MCP client!

3. **Use PowerMCP in Your AI Assistant**:
   ```
   Ask Claude: "Create a power network and run power flow analysis"
   Ask Cursor: "Load test_case.json and perform N-1 contingency analysis"
   ```

### Option 2: Use Web Interface

1. Select a power system tool (pandapower, PyPSA, or ANDES)
2. Click "List Available Tools" to see all functions
3. Enter the tool name and arguments in JSON format
4. Click "Execute Tool" to run
5. View results in JSON format

## 📖 Example Usage

### In MCP Clients (Claude Desktop, Cursor, etc.)

```python
# Create and analyze a power network
create_empty_network(server="pandapower")
load_network(file_path="test_case.json", server="pandapower")
run_power_flow(server="pandapower", algorithm="nr")
get_network_info(server="pandapower")

# Run contingency analysis
run_contingency_analysis(
    server="pandapower",
    contingency_type="N-1",
    elements=["line", "trafo"]
)

# PyPSA optimization
create_network(name="my_network", server="pypsa")
add_bus(network_name="my_network", bus_id="bus1", v_nom=380.0, server="pypsa")
run_optimization(network_name="my_network", server="pypsa")

# ANDES dynamic simulation
run_power_flow(file_path="kundur_full.json", server="andes")
run_time_domain_simulation(
    file_path="kundur_full.json",
    end_time=10.0,
    step_size=0.01,
    server="andes"
)
```

### In Web Interface

#### Create an Empty Network
```json
Tool Name: create_empty_network
Arguments: {}
```

#### Load a Network
```json
Tool Name: load_network
Arguments: {"file_path": "PowerMCP/pandapower/test_case.json"}
```

#### Run Power Flow
```json
Tool Name: run_power_flow
Arguments: {"algorithm": "nr"}
```

## 🎯 Available Tools by Server

### pandapower Tools
- `create_empty_network()` - Create new empty network
- `load_network(file_path)` - Load from JSON/pickle
- `run_power_flow(algorithm, ...)` - Power flow analysis
- `run_contingency_analysis(contingency_type, elements)` - N-1/N-2 analysis
- `get_network_info()` - Network statistics

### PyPSA Tools
- `create_network(name, snapshots, crs)` - Create PyPSA network
- `add_bus(network_name, bus_id, v_nom, x, y, carrier)` - Add bus
- `add_generator(network_name, generator_id, bus, p_nom, ...)` - Add generator
- `run_optimization(network_name)` - Optimal power flow
- `get_network_info(network_name)` - Network information

### ANDES Tools
- `run_power_flow(file_path)` - Power flow with ANDES
- `run_time_domain_simulation(file_path, end_time, step_size)` - Dynamic simulation
- `get_bus_results()` - Bus voltage/angle results

## 💻 Development

### Deploy Your Own Space

1. Fork this repository
2. Create a new Space on [Hugging Face](https://huggingface.co/new-space)
3. Choose Gradio SDK and link your repository
4. The Space will automatically get the MCP badge!

### Running Locally

```bash
git clone https://github.com/Power-Agent/PowerMCP.git
cd PowerMCP
pip install -r requirements.txt
python app.py
```

### Local MCP Configuration

For Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "pandapower": {
      "command": "/usr/local/bin/python3",
      "args": ["/path/to/PowerMCP/PowerMCP/pandapower/panda_mcp.py"]
    }
  }
}
```

## 🔗 Resources

- **GitHub**: [Power-Agent/PowerMCP](https://github.com/Power-Agent/PowerMCP)
- **MCP Docs**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
- **Tutorial**: [PowerMCP Tutorial](https://github.com/Power-Agent/PowerMCP/blob/main/PowerMCP_Tutorial.pdf)
- **Gradio MCP Guide**: [Building MCP Servers](https://www.gradio.app/guides/building-mcp-server-with-gradio)

## 🎥 Video Demos

- [Contingency Evaluation](https://www.youtube.com/watch?v=MbF-SlBI4Ws)
- [Load Growth Evaluation](https://www.youtube.com/watch?v=euFUvhhV5dM)

## 📄 License

MIT License - See [LICENSE](LICENSE) file for details

## 🤝 Contributing

Contributions welcome! PowerMCP is community-driven. Help us accelerate AI adoption in power systems.

---

Built with ❤️ by the PowerMCP Community