io.github.bch1212Published by GitHub account bch1212v0.1.0Updated Oct 26, 2026
US public-records intelligence for AI agents — companies, SEC, courts, spending, licenses.
Remote MCP server for US public-records research: companies, SEC filings, federal court cases, spending awards, licenses and grants.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.bch1212%2Fpubrecords/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"pubrecords": {
"type": "http",
"url": "https://mcp-pubrecords-production.up.railway.app/mcp/",
"headers": {
"X-API-Key": "<YOUR_API_KEY>"
}
}
}
}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.
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
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.
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.
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:
A thin Python wrapper for non-MCP integrations lives in pubrecords-sdk/:
Every MCP tool is also available over plain HTTP. Send the same X-API-Key on each call.
Production URL: https://mcp-pubrecords-production.up.railway.app
GET /usage returns the remaining daily quota for that key. GET /health is unauthenticated.
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.
Promote that same key to the paid tier (this is the single billing switch):
Run tests:
Environment variables (see .env.example):
Responses are cached for 24 hours by default.
For fresher queries, set PUBRECORDS_CACHE_TTL=300 (5 minutes). That multiplies upstream traffic.
The server returns a structured error envelope instead of invented rows when a query is outside coverage.
get_ucc_filings returns {"error": "not_implemented"} until per-state adapters land.OPENCORPORATES_TOKEN for production.form_type.SAM_API_KEY is set in the environment. Apply at https://sam.gov. The key is not embedded in this repo.search_awards reads Award Notice rows from the opportunities API. Deeper recipient rollups stay on lookup_federal_spending (USASpending).match_opportunities is deterministic token overlap on title and agency. It does not call a model.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.
Source: README.md at commit fee4b77
Search US business entities by name (OpenCorporates). Args: name: Company or trade name to search for. state: 2-letter US state code (e.g. 'CA') to narrow jurisdiction. status: Filter by current status (e.g. 'active', 'dissolved'). limit: Max results (1-100, default 25).
namerequiredlimitstatestatusFetch officers, agent, and filing history for a known company. Args: company_id: OpenCorporates company number. jurisdiction: Jurisdiction code (e.g. 'us_de', 'us_ca').
company_idrequiredjurisdictionrequiredSearch SEC EDGAR full-text for filings. Args: company_name: Issuer name or keyword. form_type: Filing form (e.g. '10-K', '10-Q', '8-K'). date_from: Earliest filing date (YYYY-MM-DD). limit: Max results (1-100, default 25).
limitdate_fromform_typecompany_namerequiredFetch metadata + index URL for one SEC filing by accession number. Args: accession_number: EDGAR accession number (e.g. '0001193125-21-000001').
accession_numberrequiredSearch federal court cases via CourtListener (RECAP). Args: party_name: Plaintiff or defendant name. court: CourtListener court id (e.g. 'nyed', 'txsd'). date_from: Earliest filing date (YYYY-MM-DD). limit: Max results (1-50, default 25).
courtlimitdate_fromparty_namerequiredSearch USASpending.gov for awards (contracts + grants). Args: recipient_name: Award recipient name. agency: Awarding agency name (e.g. 'Department of Defense'). year: Fiscal year (e.g. 2024). limit: Max results (1-100, default 25).
yearlimitagencyrecipient_namerequiredLook up healthcare providers in the NPPES NPI registry. Args: name: Provider individual or organization name. specialty: Taxonomy description (e.g. 'Internal Medicine'). state: 2-letter state code. limit: Max results (1-200, default 25).
namelimitstatespecialtyUCC lien lookup. (Roadmap; returns not_implemented per state.) Args: debtor_name: Name of the debtor. state: 2-letter state code.
staterequireddebtor_namerequiredCross-reference an entity across multiple sources and score confidence. Args: name: Entity name to verify. state: Optional 2-letter state code for jurisdiction filtering.
namerequiredstateSearch professional / business licenses (NPI + FCC, more sources roadmap). Args: entity_name: Licensee name. license_type: 'npi' | 'medical' | 'fcc' | 'radio' | 'all'. state: 2-letter state code.
stateentity_namerequiredlicense_type100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
claude mcp add --transport http halverson-iq-data https://mcp-pubrecords-production.up.railway.app/mcp/X-API-Key: YOUR_API_KEYpip install pubrecordsfrom 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"))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"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)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"}'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"}'git clone https://github.com/bch1212/mcp-pubrecords.gitcd mcp-pubrecordspython3 -m venv .venv && source .venv/bin/activatepip install -r requirements.txtcp .env.example .envuvicorn server:app --reload --port 8000pytest -v