gsa-perdiem-mcp

Free, open-source MCP server for the GSA Per Diem Rates API. Federal travel lodging and M&IE rates for IGCEs and travel cost estimation.

ZIP, state, and M&IE lookups for FY2021 onward work with no key and no network call: they are answered from GSA's published rate, ZIP, and M&IE files bundled in the package. City lookups use the GSA Per Diem API, which resolves city names to rate areas; they need a free api.data.gov key in PERDIEM_API_KEY. The hosted version needs no key for any lookup. See Local or hosted.

Tested and hardened through nine rounds of integration testing against the live GSA Per Diem API, including a round-7 independent re-audit with live verification. 564 collected Python regression tests (297 offline, 267 live-gated) covering 1 P0 path-traversal bug, 23 P1 silent-wrong-data bugs, 21 P2 validation gaps, 14 round-7 findings, the 1.1.0 rate-area ambiguity fixes, and the 1.2.1 content-test corrections. See testing.md for the full testing record.

Local or hosted

• Local runs it on your computer, inside the Claude or ChatGPT desktop app or another AI app. You get your own full rate limits, and it relies only on the government service. City lookups need a free api.data.gov key. You don't have to set it up by hand: give your AI this page's link and ask it to set it up or walk you through it.
• Hosted is the convenient option: one click, no keys, and it works in Claude or ChatGPT anywhere.

Compare local and hosted · Matching prompts

What it does

Exposes GSA per diem rates as 7 MCP tools:

Core lookups

• lookup_city_perdiem - Rates by city/state, resolved through the GSA API (optional county answers from GSA's county definitions without an API call)
• lookup_zip_perdiem - Rates by ZIP code from GSA's ZIP file (optional county)
• lookup_state_rates - All NSA rates and the standard rate for a state
• get_mie_breakdown - M&IE tier table (meal components)
• get_data_status - Bundled fiscal years, their GSA source files, and which tools call the API

Workflow

• estimate_travel_cost - Calculate trip per diem (lodging + M&IE with first/last day at 75%)
• compare_locations - Compare rates across multiple cities

Rate areas are never guessed. GSA sets rates by county or locality. When a ZIP or city spans more than one rate area with different rates, results have status: "ambiguous" and list every candidate; supplying county selects one. A city GSA does not recognize is unresolved rather than defaulting to the standard rate. When GSA lists several rate areas for a city, Census 2020 place-to-county records break the tie only if they place the city in exactly one of them. Every result names its source: the bundled GSA file (with SHA-256) or the API endpoint.

Bundled data. src/gsa_perdiem_mcp/data/ holds FY2021 onward, generated by scripts/build_snapshot.py from GSA's per diem files page and Census 2020 place/county code files. data/manifest.json records each source URL and SHA-256. The builder fails on schema drift, on any disagreement between GSA's rate and ZIP files, and on locality wording it has not been taught. FY2020 and fiscal years not yet bundled use the API.

API key (required for city lookups)

City lookups (lookup_city_perdiem, estimate_travel_cost, compare_locations) call api.gsa.gov, which requires an api.data.gov key: 1,000 requests per hour, yours alone. Without PERDIEM_API_KEY they return setup instructions instead of calling GSA. ZIP, state, and M&IE lookups for bundled fiscal years need no key.

Get a free key (takes 30 seconds):

1. Go to api.data.gov/signup
2. Enter your name and email: no approval, no wait
3. Copy the key from the confirmation page
4. Paste it into your client config as PERDIEM_API_KEY (see below)

The same key works for every api.data.gov-backed API (GSA Per Diem, NASA, FEC, FCC, etc.).

Installation

uvx gsa-perdiem-mcp

Configuration

Use the configuration below as the server definition and adapt its placement to your compatible MCP client. For practical requests using this source, see the prompt library.

With your key:

{
  "mcpServers": {
    "gsa-perdiem": {
      "command": "uvx",
      "args": ["--refresh-package", "gsa-perdiem-mcp", "--from", "gsa-perdiem-mcp", "gsa-perdiem-mcp"],
      "env": {
        "PERDIEM_API_KEY": "paste-your-api-data-gov-key-here",
        "FEDERAL_API_MIN_INTERVAL_SECONDS": "4"
      }
    }
  }
}

The server defaults FEDERAL_API_MIN_INTERVAL_SECONDS to 4 for keyed requests. The explicit value above documents the intended policy and can be changed when you have a documented reason. Per Diem and Regulations.gov processes using the same api.data.gov key share the gate.

Bundled lookups only (no key: ZIP, state, and M&IE work; city lookups return setup instructions):

{
  "mcpServers": {
    "gsa-perdiem": {
      "command": "uvx",
      "args": ["--refresh-package", "gsa-perdiem-mcp", "--from", "gsa-perdiem-mcp", "gsa-perdiem-mcp"]
    }
  }
}

The --refresh-package flag tells uv to check PyPI for a newer release each time your client launches the server, so fixes arrive automatically; without it, uv keeps serving whatever version it first cached. It adds a moment of network time at startup, so raise your platform's MCP startup timeout if it enforces a short one.

Restart the client and the tools appear.

Example prompts

• "What's the per diem rate for Washington DC in FY2026?"
• "Estimate travel costs for 4 nights in Boston in March."
• "Compare per diem rates for DC, New York, and San Francisco."
• "What are all the NSA per diem locations in Virginia?"
• "Show me the M&IE meal breakdown for the $92 tier."
• "Build a travel estimate: 3 trips to Seattle (4 nights each) and 2 trips to DC (3 nights each)."

Important: maximum reimbursement, not actual prices

Per diem rates are federal reimbursement ceilings per 41 CFR 301-11. They are not actual hotel prices. CONUS only. Non-foreign OCONUS rates (Alaska, Hawaii, territories) are set by DoD (DTMO); foreign rates by the State Department. Lodging taxes generally not included. First/last travel day M&IE at 75%.

Companion tools

Use alongside bls-oews-mcp (wage data) and gsa-calc-mcp (ceiling rates) for complete IGCE development. Per diem covers the travel component; BLS and CALC+ cover labor.

License

MIT