# us-govdata-mcp

**MCP server for US government data** — search building permits, federal contract
opportunities (SAM.gov), and the national healthcare provider registry (NPI/NPPES)
from Claude, Cursor, or any [Model Context Protocol](https://modelcontextprotocol.io) client.

<!-- GLAMA-BADGE-START -->
[![CBLU2005/us-govdata-mcp MCP server](https://glama.ai/mcp/servers/CBLU2005/us-govdata-mcp/badges/score.svg)](https://glama.ai/mcp/servers/CBLU2005/us-govdata-mcp)
<!-- GLAMA-BADGE-END -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)

All three data sources are official government publications (city open-data portals,
SAM.gov's public extract, the CMS NPPES API) — no HTML scraping, no logins, no fragile
selectors. The heavy lifting is done by three production
[Apify](https://apify.com) actors that run on **your own Apify account**.

## Try it in 30 seconds — no account, no charge

Before you decide whether this is worth an API token, run it with none:

```json
{
  "mcpServers": {
    "us-govdata": {
      "command": "npx",
      "args": ["-y", "github:CBLU2005/us-govdata-mcp"],
      "env": { "APIFY_DRY_RUN": "1" }
    }
  }
}
```

That is the whole setup. In dry-run mode every tool returns realistic sample records
**plus the exact Apify API request it would have sent** — so you can see the real shape of
the data, confirm your agent calls the tools correctly, and read the pricing disclosure in
each tool description, without creating an account, pasting a token, or spending anything.

Ask your agent something like *"find building permits over $500k issued in Austin this
month"* and watch the tool call happen end to end. When you want live data, delete the
`APIFY_DRY_RUN` line and add an `APIFY_TOKEN` (below).

## Tools

| Tool | What it searches | Typical filters | Price* |
|---|---|---|---|
| `search_building_permits` | Building permits from 10 official city/county open-data sources (NYC, Chicago, LA, Austin, SF, New Orleans, Baton Rouge, Montgomery Co. MD, Norfolk VA) — permit type, status, valuation, contractor name/license | cities, issued date range, permit type, full-text, min valuation | $0.005 / record |
| `search_federal_contract_opportunities` | Federal RFPs, solicitations, sources-sought and award notices from SAM.gov — with contracting-officer emails and phones | keyword, NAICS, notice type, set-aside (8A, WOSB, HUBZone...), agency, state, dates | $0.004 / record |
| `search_healthcare_providers` | The official CMS NPI registry of 8M+ US providers and healthcare organizations — specialty, license, practice phone/fax, authorized officials | specialty, state, city, ZIP (wildcards), provider/organization name | $0.002 / record |

\* **Honest pricing disclosure:** these tools run paid, pay-per-result Apify actors
published by [CBLU](https://apify.com/cblu). Your Apify account is charged **only for
records actually returned** — there are no subscriptions or start fees. Every tool
defaults to 25 results per call, so a typical call costs a fraction of a cent
(25 permits ≈ $0.13; 25 contract notices ≈ $0.10; 25 providers ≈ $0.05). Apify's free
plan includes monthly platform credit, which is enough to use these tools casually at
no cost. Actor pages with full pricing details:

- [US Building Permits Scraper](https://apify.com/cblu/us-building-permits-scraper)
- [SAM.gov Contract Opportunities Scraper](https://apify.com/cblu/sam-gov-contract-opportunities-scraper)
- [NPI Registry Scraper](https://apify.com/cblu/npi-healthcare-providers-scraper)

## Quick start

### 1. Get an Apify token (free, ~2 minutes)

1. Sign up at <https://console.apify.com/sign-up> (free plan works).
2. Copy your API token from <https://console.apify.com/settings/integrations>.

The server starts and lists its tools **without** a token — the token is only needed
when a tool is actually called.

### 2. Add the server to your MCP client

**Claude Desktop** (`claude_desktop_config.json` → Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "us-govdata": {
      "command": "npx",
      "args": ["-y", "github:CBLU2005/us-govdata-mcp"],
      "env": {
        "APIFY_TOKEN": "your_apify_token_here"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add us-govdata -e APIFY_TOKEN=your_apify_token_here -- npx -y github:CBLU2005/us-govdata-mcp
```

**Cursor / Windsurf / other MCP clients** (same shape as Claude Desktop):

```json
{
  "mcpServers": {
    "us-govdata": {
      "command": "npx",
      "args": ["-y", "github:CBLU2005/us-govdata-mcp"],
      "env": { "APIFY_TOKEN": "your_apify_token_here" }
    }
  }
}
```

**From a local clone:**

```bash
git clone https://github.com/CBLU2005/us-govdata-mcp.git
cd us-govdata-mcp
npm install && npm run build
# then point your client at: node /path/to/us-govdata-mcp/dist/index.js
```

**Docker:**

```bash
docker build -t us-govdata-mcp .
docker run -i --rm -e APIFY_TOKEN=your_apify_token_here us-govdata-mcp        # stdio
docker run --rm -p 3000:3000 -e APIFY_TOKEN=... us-govdata-mcp --http 3000    # Streamable HTTP
```

### 3. Ask your AI agent things like

- *"Find building permits for new construction over $500k issued in Austin this month, with contractor names."*
- *"Any active small-business set-aside cybersecurity solicitations with a response deadline after today? Include the contracting officer's email."*
- *"List dentists in the greater Miami area (ZIP 331*) with their practice phone numbers."*

## Transports

- **stdio** (default) — what desktop MCP clients use: `us-govdata-mcp`
- **Streamable HTTP** — stateless endpoint at `POST /mcp`, health check at `GET /healthz`:
  `us-govdata-mcp --http 3000` (or set `MCP_HTTP_PORT=3000`)

## Environment variables

| Variable | Required | Purpose |
|---|---|---|
| `APIFY_TOKEN` | For tool calls | Your Apify API token. Server start & tool listing work without it; tool calls return a setup guide until it is set. |
| `APIFY_DRY_RUN` | No | Set to `1` to return canned sample records **without any network call or charge** — the response includes the exact Apify API request that would have been sent. Useful for testing and CI. |
| `MCP_HTTP_PORT` | No | Start in Streamable HTTP mode on this port instead of stdio. |

## How it works

Each tool validates its arguments (zod), builds the actor input, and calls the Apify
API's [`run-sync-get-dataset-items`](https://docs.apify.com/api/v2#/reference/actors/run-actor-synchronously-and-get-dataset-items)
endpoint with your token via an `Authorization: Bearer` header (never in the URL).
The actor runs on the Apify platform under your account and the resulting dataset
items are returned directly as the tool result. This server keeps no state and sees
no data beyond passing it through.

## Development

```bash
npm install
npm test          # builds + runs the full smoke suite (introspection, tokenless
                  # error path, dry-run request construction, HTTP transport)
```

The test suite needs **no Apify account and no network** — it uses `APIFY_DRY_RUN=1`.

## Related

- Apify Store profile with all CBLU actors: <https://apify.com/cblu>
- Model Context Protocol: <https://modelcontextprotocol.io>

## License

[MIT](LICENSE) © CBLU