# us-gov-data-mcp

**An MCP server for US government data. Ask your AI assistant which federal contracts are expiring, or which public companies had the most revenue last year — and get answers you can verify against the government's own records.**

Built on the US Treasury's [USAspending](https://www.usaspending.gov) API and the SEC's [EDGAR XBRL](https://data.sec.gov) data. No scraping, no API key, no account, no personal data.

---

## Why this exists

Both of these sources publish everything and let you query almost none of it.

**usaspending.gov cannot search by contract end date.** But when a federal contract's period of performance ends, the work usually has to be re-competed — and those recompetes are the highest-probability opportunities in government contracting, visible in public data months before any solicitation appears.

**sec.gov serves filings one company at a time.** There is no way on the site to ask which public companies had revenue over $100 billion, or which hold the most cash. The SEC's `frames` API can answer that across all ~5,800 filers in one call, if you already know the XBRL tag *and* the period format.

This server answers the questions those sites can't.

## Four tools

### `find_expiring_contracts` — recompetes

Federal contracts coming up for re-bid, with the incumbent and days remaining. `expiring_after_days` sets your bid lead time, because a contract ending next week is useless to prepare for.

```json
{
  "days_until_expiry": 120,
  "recipient": "PERATON ENTERPRISE SOLUTIONS LLC",
  "amount_usd": 682369225.00,
  "awarding_agency": "General Services Administration",
  "verify_url": "https://www.usaspending.gov/award/..."
}
```

### `search_federal_contracts`

Awarded contracts by agency, keyword, date, or dollar amount. Who is winning federal work, what an agency spends, a competitor's history.

### `screen_public_companies`

Rank every US public company by any reported financial metric.

> *"Which companies had revenue over $200 billion in 2023?"*

```json
{ "company": "Walmart Inc.", "value": 648125000000, "unit": "USD",
  "period_end": "2023-12-31", "period_type": "annual",
  "verify_url": "https://www.sec.gov/Archives/edgar/data/104169/..." }
```

### `company_financial_history`

One company's reported history of a metric — revenue, net income, assets, cash flow — deduplicated, with the form type and filing date on each record.

## Everything is verifiable

Each record carries a `verify_url` to the government filing it came from. Open it and compare.

That matters most with an AI in the loop: when an assistant reports a dollar figure, you should be able to check it against the source rather than trust the chain. If a value ever disagrees with the official record, that is a bug — please open an issue.

## Three traps this handles for you

Raw SEC data misleads in three specific ways, each **silent** — you get a plausible wrong number, not an error.

1. **A 10-Q reports the quarter *and* the year-to-date with the same end date.** Comparing net income across filings silently mixes a three-month figure with a nine-month one. Every record carries `period_type`, and you can filter on it.
2. **The same fact recurs across filings with different values.** This year's 10-K restates last year's figures. Deduplicated to one record per period, most recent filing winning — the SEC's own treatment of restatements.
3. **Companies switch XBRL tags over time.** Microsoft filed `Revenues` until 2010 and a different tag afterwards. Taking the first tag that returns data yields a stale partial history; this merges across all of them.

## Install

```bash
uvx --from git+https://github.com/groundtruthtools/us-gov-data-mcp us-gov-data-mcp
```

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "us-gov-data": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/groundtruthtools/us-gov-data-mcp",
        "us-gov-data-mcp"
      ],
      "env": { "SEC_USER_AGENT": "Your Name your@email.com" }
    }
  }
}
```

Works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code.

**`SEC_USER_AGENT` is worth setting.** SEC's fair-access policy requires a User-Agent containing a contact address, and requests without one get a 403. A default is included so the tools work out of the box, but identifying yourself is the polite thing and keeps you off a shared identity.

*One quirk, learned the hard way: **do not put a URL in that string.** SEC returns 403 for any User-Agent containing one. `Your Name your@email.com` works; adding `github.com/...` does not.*

*Not on PyPI yet, so install from the repository. When it lands there this becomes a plain `uvx us-gov-data-mcp`.*

## Honest limits

- **Contracts: awarded, not open solicitations.** For published bids, use SAM.gov.
- **Contracts: federal only**, no data before fiscal year 2008.
- **Recompete search covers contracts with activity in the past year**, because USAspending caps how deep results can be paged. A long-dormant contract may not appear, and an over-broad search says so rather than returning a confidently empty list.
- **SEC: XBRL coverage starts around 2009**, and only covers concepts companies actually tagged. Smaller filers tag less.
- **It reports; it does not compute.** No ratios, growth rates, or derived metrics — those would be our arithmetic rather than the filing, and you could not verify them against the source.
- **Not investment advice.** It is a data-reformatting tool.

## Also on Apify

The same logic runs as hosted tools, no install required:

- [US Federal Contract Awards & Recompete Finder](https://apify.com/groundtruth/usaspending-government-contracts)
- [SEC EDGAR Financial Data & Company Screener](https://apify.com/groundtruth/sec-edgar-financial-data)

## Data sources and licence

Contracts: [USAspending.gov](https://www.usaspending.gov), US Department of the Treasury, published under the DATA Act.
Financials: [SEC EDGAR](https://www.sec.gov/edgar), US Securities and Exchange Commission.
Both public domain. Code: MIT.