PolicyEngine Macro

mcp · cli · python

Run a model your way.

Three routes to the same models. Start with MCP below — it needs no install, no PolicyEngine account and no API key, though some clients gate custom connectors by plan. That is true of the hosted route; a local UK population or reform-scoring run additionally needs a HuggingFace token, as below. Use the CLI or Python when you want the models in a script, or need one of the local-only members.

hosted

Connect in three steps.

1

Copy the server URL

https://policyengine--policyengine-macro-mcp-serve.modal.run/mcp
2

Add a Claude connector

On claude.ai or in the Claude Desktop app, open Settings → Connectors, choose “Add custom connector”, and paste the URL.

3

Ask a policy question

A US rate shock, a UK forecast, a household reform — copy an example prompt below.

example prompts
  • calculate_householdHow much tax would a single 35-year-old earning $50,000 pay in the US?
  • score_reformScore raising the UK basic rate of income tax to 21p.
  • forecast_ukWhat is the UK GDP and inflation outlook for the next four quarters?
  • frbus_shockWhat happens to US GDP and unemployment if the Fed raises rates by 100 basis points?
  • hank_shockHow does a 25 basis point US rate cut hit households across the wealth distribution?
Terminal setup
claude mcp add --transport http policyengine-macro https://policyengine--policyengine-macro-mcp-serve.modal.run/mcp

access No account, no API key. Fair use, a few concurrent runs.

cold start ~20s on the first household or population call while the tax-benefit models load; a couple of minutes for a first UK forecast. Warm calls are fast.

uk microdata Only a local UK population or reform score needs HUGGING_FACE_TOKEN (private policyengine-uk-data-private). Hosted calls need nothing.

local only Three things are not hosted: model='og' and dynamic_reform_impact (tens of minutes), and the define_* tools (unlicensed upstream). Called here they return run instructions or an import error, not results — use the CLI. Everything else runs hosted.

terminal

Run the shared CLI.

Install once, then choose a model command.

pip install "policyengine-macro[models] @ git+https://github.com/PolicyEngine/macro#subdirectory=integration"
Household calculation
pe-macro household --country us --people '[{"age":35,"employment_income":50000}]'
Score a UK reform
pe-macro score --country uk --reform '{"gov.hmrc.income_tax.rates.uk[0].rate":0.21}' --model obr
UK forecast
pe-macro forecast
US rate shock
pe-macro frbus-shock --var rffintay_aerr --shock 1.0
US HANK shock
pe-macro hank-shock --kind monetary --size -0.0025

View every CLI command → · How the micro-to-macro scoring pipeline works: score a reform.

python

Use Python directly.

Choose a model for its install and API reference.

hosted

UK and US household impacts

Taxes, benefits, net income and reform effects, household by household — PolicyEngine’s own engine, and the usual starting point. It cannot answer GDP, inflation, interest rates or macro feedback; the macro models below add those.

Open PolicyEngine setup