Metadata-Version: 2.5
Name: gsa-perdiem-mcp
Version: 1.2.6
Summary: MCP server for GSA Per Diem Rates API. Federal travel lodging and M&IE rates for IGCEs and travel cost estimation.
Project-URL: Homepage, https://1102tools.com
Project-URL: Repository, https://github.com/1102tools-dev/federal-contracting-mcps
Project-URL: Issues, https://github.com/1102tools-dev/federal-contracting-mcps/issues
Author: James Jenrette / 1102tools
License: MIT
Keywords: 1102,federal-contracts,gsa,lodging,mcp,mie,model-context-protocol,per-diem,travel
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: filelock>=3.13
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: platformdirs>=4.0
Description-Content-Type: text/markdown

# gsa-perdiem-mcp

[![price: free](https://img.shields.io/badge/price-free-007a59)](https://1102tools.com/#why) [![license: MIT](https://img.shields.io/badge/license-MIT-007a59)](license) [![tools: 7](https://img.shields.io/badge/tools-7-007a59)](#what-it-does) [![regression tests](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/1102tools-dev/federal-contracting-mcps/main/badges/tests-gsa-perdiem-mcp.json)](testing.md)

<!-- mcp-name: com.1102tools/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. For bundled fiscal years, city lookups, trip estimates and comparisons with a supplied `county` also work without a key or network call. City-name lookups without a county are answered from bundled Census place and GSA county data when that settles the rate area; other city names and lookups for unbundled years use the GSA Per Diem API and need a free api.data.gov key in `PERDIEM_API_KEY`. The hosted version needs no key for any lookup. See [Local or hosted](#local-or-hosted).

*Regression tests, and realistic contractor travel questions checked against GSA's published rates before release. See [testing.md](testing.md).*

## Local or hosted

| Local (desktop) | Claude (hosted) | ChatGPT (hosted) |
|---|---|---|
| [Local setup](#installation) | [Install](https://claude.ai/directory/gsa-perdiem-by-1102tools) | [Install](https://chatgpt.com/plugins/plugin_asdk_app_6ab85f56d4ec8191970ab75fdeddd2f9) |

- **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. Bundled ZIP, state, M&IE and city-plus-county requests need no key. Only live API requests need a free api.data.gov key. It doesn't update itself, so ask your AI to update it. 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 always up to date, needs no setup or keys, and works in Claude or ChatGPT anywhere.

[Compare local and hosted](../../#local-or-hosted) · [Matching prompts](https://1102tools.com/#gsa-per-diem)

## What it does

Exposes GSA per diem rates as 7 MCP tools:

**Core lookups**
- `lookup_city_perdiem` - Rates by city/state, from bundled Census and county data when the city falls in one rate area, otherwise through the GSA API (optional `county` selects one)
- `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 is placed in a rate area by GSA's county definitions, using Census 2020 place-to-county records; a name Census doesn't list goes to GSA, and one GSA also doesn't 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 (only for live API requests)

ZIP, state and M&IE requests for bundled fiscal years work without a key. So do `lookup_city_perdiem`, `estimate_travel_cost` and `compare_locations` when you supply a county for the bundled year. For example, ask for Boston, MA, in Suffolk County, or include `county: "Suffolk"` in each Boston comparison entry.

City-name requests that bundled Census and county data can't settle, and lookups for unbundled years, call `api.gsa.gov` and require an api.data.gov key: 1,000 requests per hour, yours alone. Without `PERDIEM_API_KEY`, those API requests return setup instructions. You can instead supply the work-location county for a bundled year to complete a city lookup or travel estimate without setting up a key.

**Get a free key (takes 30 seconds):**

1. Go to [api.data.gov/signup](https://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

```bash
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](https://github.com/1102tools-dev/federal-contracting-prompts).

**With your key:**
```json
{
  "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 `0.6` for keyed
requests and caps them at 950 per hour. The example above sets a slower
`4`; either works. Per Diem and
Regulations.gov processes using the same `api.data.gov` key share the gate.

**No-key setup** (bundled ZIP, state, M&IE, and city-plus-county lookups, estimates and comparisons work):
```json
{
  "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

**Trips crossing months or fiscal years.** Add each month's `lodging_total` at the applicable fiscal year rate. Calculate M&IE once across the actual travel days: 75% on the departure and return days, 100% on intervening days. Do not add separate monthly `mie_total` or `grand_total` values because each estimate assumes its own departure and return. For example, four nights at a $92 daily M&IE rate cost $414 M&IE over five travel days; two independent two-night estimates sum to $460 M&IE.
