Metadata-Version: 2.5
Name: fedfinder-mcp
Version: 1.0.0
Summary: Federal contracting data as MCP tools: opportunities, awards, vendors, people and grants, already filtered for what is actually biddable.
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# FedFinder MCP server

Federal contracting data as tools your agent can call: open solicitations,
21M award records, 885k registered entities, 1M contracting people, and grants.

## Why not just call SAM.gov

You can, and it is free. The reason people stop is that the raw feeds do not
answer the question you actually asked.

SAM.gov's `active` flag does not mean "open for bid". A notice with no response
deadline stays active forever, because the retirement sweeps key on the
deadline. Measured on FedFinder's production corpus, **one row in five that the
raw feed calls open is a notice SAM already archived**, including one posted in
2008 and archived twelve days later. Grants have the same shape: SAM assistance
listings describe standing programmes with no application and no deadline, and
they outnumber the real opportunities.

Every tool here filters that out before it answers. That is the product.

## Setup

```bash
pip install fedfinder-mcp
export FEDFINDER_API_KEY=fedf_live_...
```

Get a key at <https://app.fedfinder.net>. Standalone API access is $49/month:
30 requests per minute, 50,000 calls per month.

### Claude Desktop

```json
{
  "mcpServers": {
    "fedfinder": {
      "command": "fedfinder-mcp",
      "env": { "FEDFINDER_API_KEY": "fedf_live_..." }
    }
  }
}
```

## Tools

| tool | scope required |
|---|---|
| `search_opportunities` | `opportunities:read` |
| `get_opportunity` | `opportunities:read` |
| `search_state_opportunities` | `state-opportunities:read` |
| `search_contracts` | `contracts:read` |
| `search_vendors` | `vendors:read` |
| `search_people` | `people:read` (Intel) |
| `search_grants` | `grants:read` |
| `search_pre_rfp_signals` | `pre-rfp-signals:read` (Intel) |
| `list_captures` | `captures:read` |
| `list_win_loss` | `winloss:read` |
| `api_info` | any |

Keys are scoped. A tool whose scope your key lacks returns a message naming the
missing scope rather than an opaque 403. Omit `scopes` when minting a key to
grant all read scopes.

## Things worth knowing

**State filtering is asymmetric on purpose.** SAM omits place of performance on
about half of all notices, so a bare equality test hides most of the market. A
row with no stated performance location falls back to the contracting office's
state; a row that states a *different* location is never rescued by its office,
because a DC office buys work performed in Guam and treating those as the same
fact would swap a silent miss for a confident error.

**Names are stored inverted at the source.** "Smith, John", not "John Smith".
`search_people` handles it; if you are joining against another system, do not
assume the ordering matches.

**Grant close dates are free text.** Several formats arrive, some as vague as a
bare year. Treat anything you cannot parse as "rolling or unknown" rather than
inventing a date, which would close a grant that is still live.

**Municipal money is not here.** City and county programmes are not tracked by
any platform, FedFinder included. If that is what you need, a human has to call
the city.

## Rate limits

30 requests per minute on the standalone plan, higher on Pro and Intel. A 429
means wait, not retry immediately. `api_info` reports what your key carries.
