{"id":31033240,"url":"https://github.com/policyengine/policyengine-mcp","last_synced_at":"2025-09-14T01:40:19.448Z","repository":{"id":314633845,"uuid":"1053498115","full_name":"PolicyEngine/policyengine-mcp","owner":"PolicyEngine","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-09T14:29:03.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T18:50:32.798Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PolicyEngine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T14:28:58.000Z","updated_at":"2025-09-09T14:29:08.000Z","dependencies_parsed_at":"2025-09-13T18:50:34.528Z","dependency_job_id":"c4717d84-ca7a-45be-ba21-28b86d4d34a0","html_url":"https://github.com/PolicyEngine/policyengine-mcp","commit_stats":null,"previous_names":["policyengine/policyengine-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/PolicyEngine/policyengine-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PolicyEngine","download_url":"https://codeload.github.com/PolicyEngine/policyengine-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275051513,"owners_count":25396978,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-14T01:40:15.795Z","updated_at":"2025-09-14T01:40:19.436Z","avatar_url":"https://github.com/PolicyEngine.png","language":"Python","readme":"# PolicyEngine MCP Server\n\nAn MCP (Model Context Protocol) server that provides access to PolicyEngine's database and simulation capabilities.\n\n## Features\n\n- **Database access**: Query variables, parameters, policies, and datasets from PolicyEngine database\n- **Simulation running**: Execute tax-benefit simulations with different policies and datasets\n- **Statistical analysis**: Calculate aggregates and counts on simulation results\n- **Raw SQL queries**: Execute read-only SQL queries for advanced analysis\n\n## Installation\n\n```bash\n# Install with uv\nuv pip install -e .\n\n# Or with pip\npip install -e .\n```\n\n## Usage with Claude Code\n\n### Quick setup\n\nRun the setup script:\n```bash\n./setup_claude.sh\n```\n\n### Manual setup\n\nAdd the PolicyEngine MCP server to Claude Code:\n\n```bash\n# Add with environment variable for database password\nclaude mcp add policyengine \\\n  --env POLICYENGINE_DB_PASSWORD=your_password_here \\\n  --env PYTHONPATH=/path/to/policyengine.py/src \\\n  -- python -m policyengine_mcp.server\n\n# Or if you have the password in your environment already\nclaude mcp add policyengine \\\n  --env PYTHONPATH=/path/to/policyengine.py/src \\\n  -- python -m policyengine_mcp.server\n```\n\n### Environment variables\n\nRequired for live database connection:\n- `POLICYENGINE_DB_PASSWORD`: Your PolicyEngine database password\n- `PYTHONPATH`: Path to policyengine.py/src directory\n\nOptional:\n- `POLICYENGINE_DB_USER`: Database user (defaults to PolicyEngine's standard user)\n- `POLICYENGINE_DB_HOST`: Database host (defaults to PolicyEngine's AWS endpoint)\n- `POLICYENGINE_DB_PORT`: Database port (defaults to 5432)\n- `POLICYENGINE_DB_NAME`: Database name (defaults to postgres)\n\n## Available tools\n\n### Database connection\n- `connect_database`: Connect to PolicyEngine database (use \"live\" for production)\n\n### Data queries\n- `list_variables`: List tax-benefit variables\n- `list_parameters`: List policy parameters\n- `list_policies`: List available policies\n- `list_datasets`: List available datasets\n- `get_variable`: Get details of a specific variable\n- `get_parameter`: Get details of a specific parameter\n\n### Simulation\n- `run_simulation`: Run a tax-benefit simulation\n- `list_simulations`: List existing simulations from the database\n- `get_simulation`: Get details of a specific simulation\n- `calculate_aggregate`: Calculate statistics (mean, median, sum) from simulation results - supports batch processing\n- `calculate_count`: Count entities matching conditions - supports batch processing\n\n### Advanced\n- `query_raw`: Execute read-only SQL queries\n\n## Example usage\n\nOnce connected via Claude Desktop, you can ask questions like:\n\n- \"What variables are available for UK benefits?\"\n- \"List existing simulations for UK 2024\" (check before running new simulations!)\n- \"Run a simulation for UK 2024 and calculate average household income\"\n- \"How many people receive universal credit in the baseline?\"\n- \"What is the total government spending on child benefit?\"\n\n### Analysing the current status quo\n\nThe 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:\n\n**Income and wealth distribution:**\n- Average household income by region or demographic group\n- Income inequality metrics (using different percentiles)\n- Wealth distribution across age bands\n\n**Government finances:**\n- Total tax revenue by tax type (income tax, VAT, etc.)\n- Total spending on each benefit programme\n- Net fiscal position by household type\n\n**Benefit system analysis:**\n- Number of recipients for each benefit\n- Average payment amounts by benefit type\n- Benefit participation rates\n- Poverty rates before and after benefits\n\n**Labour market insights:**\n- Employment rates by demographic\n- Distribution of earnings\n- Effective marginal tax rates\n\nExample: To analyse UK benefit spending in 2024:\n1. Find or create a simulation: `dataset=\"uk_2024\"`, `policy=\"Current law\"`, `dynamic=\"Static\"`\n2. Use batch processing to get all benefit totals at once:\n   ```json\n   {\n     \"simulation_id\": \"...\",\n     \"aggregates\": [\n       {\"variable\": \"universal_credit\", \"metric\": \"sum\"},\n       {\"variable\": \"child_benefit\", \"metric\": \"sum\"},\n       {\"variable\": \"housing_benefit\", \"metric\": \"sum\"},\n       {\"variable\": \"pension_credit\", \"metric\": \"sum\"}\n     ]\n   }\n   ```\n\n### Best practices\n\n1. **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.\n\n2. **Reuse simulation IDs**: After finding or creating a simulation, use its ID with `calculate_aggregate` and `calculate_count` for analysis.\n\n3. **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:\n   ```json\n   {\n     \"simulation_id\": \"...\",\n     \"aggregates\": [\n       {\"variable\": \"income\", \"metric\": \"mean\"},\n       {\"variable\": \"benefits\", \"metric\": \"sum\"},\n       {\"variable\": \"tax\", \"metric\": \"median\"}\n     ]\n   }\n   ```\n\n## Development\n\n```bash\n# Install development dependencies\nuv pip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nruff format .\n\n# Lint code\nruff check .\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolicyengine%2Fpolicyengine-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolicyengine%2Fpolicyengine-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolicyengine%2Fpolicyengine-mcp/lists"}