https://github.com/policyengine/policyengine-mcp
https://github.com/policyengine/policyengine-mcp
Last synced: 7 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/policyengine/policyengine-mcp
- Owner: PolicyEngine
- Created: 2025-09-09T14:28:58.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-09-09T14:29:03.000Z (7 months ago)
- Last Synced: 2025-09-13T18:50:32.798Z (7 months ago)
- Language: Python
- Size: 12.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# PolicyEngine MCP Server
An MCP (Model Context Protocol) server that provides access to PolicyEngine's database and simulation capabilities.
## Features
- **Database access**: Query variables, parameters, policies, and datasets from PolicyEngine database
- **Simulation running**: Execute tax-benefit simulations with different policies and datasets
- **Statistical analysis**: Calculate aggregates and counts on simulation results
- **Raw SQL queries**: Execute read-only SQL queries for advanced analysis
## Installation
```bash
# Install with uv
uv pip install -e .
# Or with pip
pip install -e .
```
## Usage with Claude Code
### Quick setup
Run the setup script:
```bash
./setup_claude.sh
```
### Manual setup
Add the PolicyEngine MCP server to Claude Code:
```bash
# Add with environment variable for database password
claude mcp add policyengine \
--env POLICYENGINE_DB_PASSWORD=your_password_here \
--env PYTHONPATH=/path/to/policyengine.py/src \
-- python -m policyengine_mcp.server
# Or if you have the password in your environment already
claude mcp add policyengine \
--env PYTHONPATH=/path/to/policyengine.py/src \
-- python -m policyengine_mcp.server
```
### Environment variables
Required for live database connection:
- `POLICYENGINE_DB_PASSWORD`: Your PolicyEngine database password
- `PYTHONPATH`: Path to policyengine.py/src directory
Optional:
- `POLICYENGINE_DB_USER`: Database user (defaults to PolicyEngine's standard user)
- `POLICYENGINE_DB_HOST`: Database host (defaults to PolicyEngine's AWS endpoint)
- `POLICYENGINE_DB_PORT`: Database port (defaults to 5432)
- `POLICYENGINE_DB_NAME`: Database name (defaults to postgres)
## Available tools
### Database connection
- `connect_database`: Connect to PolicyEngine database (use "live" for production)
### Data queries
- `list_variables`: List tax-benefit variables
- `list_parameters`: List policy parameters
- `list_policies`: List available policies
- `list_datasets`: List available datasets
- `get_variable`: Get details of a specific variable
- `get_parameter`: Get details of a specific parameter
### Simulation
- `run_simulation`: Run a tax-benefit simulation
- `list_simulations`: List existing simulations from the database
- `get_simulation`: Get details of a specific simulation
- `calculate_aggregate`: Calculate statistics (mean, median, sum) from simulation results - supports batch processing
- `calculate_count`: Count entities matching conditions - supports batch processing
### Advanced
- `query_raw`: Execute read-only SQL queries
## Example usage
Once connected via Claude Desktop, you can ask questions like:
- "What variables are available for UK benefits?"
- "List existing simulations for UK 2024" (check before running new simulations!)
- "Run a simulation for UK 2024 and calculate average household income"
- "How many people receive universal credit in the baseline?"
- "What is the total government spending on child benefit?"
### Analysing the current status quo
The MCP server is particularly powerful for analysing the current economic and policy landscape. When you have a simulation with "Current law" policy, "Static" dynamic settings, and a representative dataset for a country, you can calculate comprehensive statistics about the status quo:
**Income and wealth distribution:**
- Average household income by region or demographic group
- Income inequality metrics (using different percentiles)
- Wealth distribution across age bands
**Government finances:**
- Total tax revenue by tax type (income tax, VAT, etc.)
- Total spending on each benefit programme
- Net fiscal position by household type
**Benefit system analysis:**
- Number of recipients for each benefit
- Average payment amounts by benefit type
- Benefit participation rates
- Poverty rates before and after benefits
**Labour market insights:**
- Employment rates by demographic
- Distribution of earnings
- Effective marginal tax rates
Example: To analyse UK benefit spending in 2024:
1. Find or create a simulation: `dataset="uk_2024"`, `policy="Current law"`, `dynamic="Static"`
2. Use batch processing to get all benefit totals at once:
```json
{
"simulation_id": "...",
"aggregates": [
{"variable": "universal_credit", "metric": "sum"},
{"variable": "child_benefit", "metric": "sum"},
{"variable": "housing_benefit", "metric": "sum"},
{"variable": "pension_credit", "metric": "sum"}
]
}
```
### Best practices
1. **Always check existing simulations first**: Use `list_simulations` before running `run_simulation` to avoid expensive duplicate computations. The server will warn you if a simulation already exists and return the existing one instead.
2. **Reuse simulation IDs**: After finding or creating a simulation, use its ID with `calculate_aggregate` and `calculate_count` for analysis.
3. **Use batch processing for multiple calculations**: When calculating multiple aggregates or counts, use the batch mode by passing an array of specifications. This is much more efficient than multiple individual calls:
```json
{
"simulation_id": "...",
"aggregates": [
{"variable": "income", "metric": "mean"},
{"variable": "benefits", "metric": "sum"},
{"variable": "tax", "metric": "median"}
]
}
```
## Development
```bash
# Install development dependencies
uv pip install -e ".[dev]"
# Run tests
pytest
# Format code
ruff format .
# Lint code
ruff check .
```