io.github.bch1212/pubrecords

Halverson IQ Data

One paid MCP server for US public records, federal grants, and federal contracts. Companies, SEC filings, court dockets, spending awards, licenses, Grants.gov opportunities, and SAM.gov contract notices share a single API key and a single bill.

What this server includes

This repository is the combined Halverson IQ Data server.

Not part of this server: business-intel and outdoor datasets (separate or retired), and web-page fetching (a different pipeline with its own fetchers and cache).

One customer key is checked on every tool. Free tier is 30 calls/day across the whole server. Pro is unlimited on the same key. Upgrade: https://mcpize.com/pubrecords-mcp

Pricing

Keys are issued per user. Ask the operator for a key, or have them mint one with POST /admin/keys. Examples below use the placeholder YOUR_API_KEY.

Tool reference

Public records

Grants and federal contracts

focus_areas on the REST route is a comma-separated string. The MCP tool accepts a list.

Contract tools call SAM.gov only when SAM_API_KEY is set. If it is missing they return {"success": false, "error": "SAM_API_KEY is not configured"} and do not send a request.

Install in Claude

claude mcp add --transport http halverson-iq-data https://mcp-pubrecords-production.up.railway.app/mcp/

Note the trailing slash on /mcp/. Without it the gateway issues a 307 that drops the POST body, breaking the JSON-RPC handshake.

Then set the API key in your client:

X-API-Key: YOUR_API_KEY

Python SDK

A thin Python wrapper for non-MCP integrations lives in pubrecords-sdk/:

pip install pubrecords

from pubrecords import PubRecords

client = PubRecords(api_key="YOUR_API_KEY")
print(client.health())
print(client.search_companies(name="Apple", state="CA"))
print(client.search_grants(keyword="broadband"))

REST surface

Every MCP tool is also available over plain HTTP. Send the same X-API-Key on each call.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://mcp-pubrecords-production.up.railway.app/tools/search_companies?name=Apple&state=CA"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://mcp-pubrecords-production.up.railway.app/tools/search_grants?keyword=broadband"

Production URL: https://mcp-pubrecords-production.up.railway.app

GET  /health                          (no auth)
GET  /usage                           (X-API-Key)
GET  /tools/<tool_name>?...           (X-API-Key)
POST /admin/keys                      (X-Admin-Token; fails closed)
POST /billing/upgrade                 (X-Admin-Token; fails closed)
POST /mcp/                            (MCP streamable-http transport)

GET /usage returns the remaining daily quota for that key. GET /health is unauthenticated.

Issuing a customer key

POST /admin/keys and POST /billing/upgrade return 403 unless PUBRECORDS_ADMIN_TOKEN is set and the X-Admin-Token header matches it. There is no default admin token.

curl -X POST https://mcp-pubrecords-production.up.railway.app/admin/keys \
  -H "X-Admin-Token: $PUBRECORDS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_API_KEY","tier":"free"}'

Promote that same key to the paid tier (this is the single billing switch):

curl -X POST https://mcp-pubrecords-production.up.railway.app/billing/upgrade \
  -H "X-Admin-Token: $PUBRECORDS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_API_KEY"}'

Local development

git clone https://github.com/bch1212/mcp-pubrecords.git
cd mcp-pubrecords
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn server:app --reload --port 8000

Run tests:

pytest -v

Environment variables (see .env.example):

Data freshness

Responses are cached for 24 hours by default.

For fresher queries, set PUBRECORDS_CACHE_TTL=300 (5 minutes). That multiplies upstream traffic.

Data gaps and source limits

The server returns a structured error envelope instead of invented rows when a query is outside coverage.

1. UCC filings — there is no uniform federal UCC API. get_ucc_filings returns {"error": "not_implemented"} until per-state adapters land.
2. State professional licenses — healthcare (NPI) and FCC are covered. Bar, real estate, contractor, and CPA licenses are state-by-state.
3. OpenCorporates rate limits — anonymous traffic is capped. Set OPENCORPORATES_TOKEN for production.
4. SEC EDGAR full-text — broad terms return wide sets. Combine with form_type.
5. CourtListener — federal PACER/RECAP. State courts are not guaranteed.
6. SAM.gov — contract tools do nothing until SAM_API_KEY is set in the environment. Apply at https://sam.gov. The key is not embedded in this repo.
7. SAM award history — search_awards reads Award Notice rows from the opportunities API. Deeper recipient rollups stay on lookup_federal_spending (USASpending).
8. Match scores — match_opportunities is deterministic token overlap on title and agency. It does not call a model.
9. No consumer PII — entity-level public records only.

License and compliance

This server proxies and caches public records that are already free to access from federal and public sources. Cached payloads are kept for 24 hours and can be flushed by deleting the SQLite file. Customer API keys and the admin token belong in the environment and the SQLite key store. Do not commit them.