Capitol Ledger

Capitol Ledger MCP

Read-only congressional stock disclosure research for AI agents. Search official U.S. House disclosures, inspect saved synthetic disclosure-ledger portfolios, and explain portfolio changes with source and timing context.

Request pilot access · API documentation · PyPI package · Official MCP Registry · Public fictional sample · Methodology

Access

The adapter is open source. The hosted data API requires an approved Capitol Ledger API key. Request an invited free 14-day pilot at the link above. Approved pilot accounts default to 1,000 authenticated requests per UTC day, shared across keys. No payment details or automatic paid conversion. Submitting an application does not grant access or subscribe you to a newsletter.

The public JSON sample is fictional and requires no key. It is useful for inspecting the response shape; it is not a real disclosure or live data.

Install

Python 3.12 or later is required. Install the published PyPI package:

pip install capitol-ledger-mcp

Or run without a permanent installation:

uvx --from capitol-ledger-mcp capitol-ledger-mcp

To install from this public repository instead:

pip install 'git+https://github.com/joalbrecht/capitol-ledger-mcp.git'

Connect your MCP client

For an installed adapter, use this local stdio configuration:

{
  "mcpServers": {
    "capitol-ledger": {
      "command": "capitol-ledger-mcp",
      "env": {
        "CAPITOL_LEDGER_API_URL": "https://capitol-ledger.com",
        "CAPITOL_LEDGER_API_KEY": "YOUR_APPROVED_API_KEY"
      }
    }
  }
}

Replace the placeholder locally and keep the key in your client's secret store. Do not put it in a shared prompt, URL, issue, or public repository. If your client cannot find the command, use its absolute installation path.

A client using uvx can instead use "command": "uvx" and "args": ["--from", "capitol-ledger-mcp", "capitol-ledger-mcp"], with the same env. This is a local stdio server that calls a hosted HTTPS API. It is not a hosted remote MCP endpoint. No broker or trading-account credentials are needed.

Tools

Tool	Purpose	Parameters
search_disclosures	Search House stock disclosures with filing links and amount ranges	Optional ticker, side, available_after, as_of, limit, offset
get_portfolio	Opening/closing allocations for a saved synthetic ledger report	Optional report_id, as_of
get_portfolio_changes	Purchases, sales, and allocation changes for a saved period	Optional report_id, as_of

Example questions after connecting:

• What NVDA purchases were disclosed in the last 30 days? Include source links.
• Show the latest saved synthetic disclosure portfolio and its period.
• What changed in that report? Use the same report ID.

Search defaults to 30 days, with at most 100 rows per call. side accepts purchase, sale, or exchange. Timestamps must include a timezone. Reuse returned as_of and available_after when paging with meta.next_offset. Pin report_id to compare a portfolio and its changes over the same period.

Coverage and interpretation

• House only. Senate data is excluded.
• Disclosures are delayed. The transaction date, public filing availability, and collection time are separate; do not describe a newly filed disclosure as a trade that just happened.
• Disclosed amounts are ranges, not exact transaction values. Synthetic ledger values use midpoint estimates.
• Portfolio snapshots represent a synthetic disclosure ledger, not actual member holdings or Capitol Ledger's executable strategy portfolio. Reports may be daily, weekly, monthly, or ad hoc; inspect returned period metadata.
• Preserve source URLs, calculation metadata, freshness, and coverage warnings. Completeness is not guaranteed. Historical queries use current parsed records, not a complete versioned archive of parser/source revisions.
• Research data only; no personalized investment advice or order execution.
• Pilot access is for internal research workflows; contact Capitol Ledger about redistribution or serving downstream users. The code's MIT license does not grant redistribution rights to the hosted data.

Usage and errors

All three tools use the API's account-wide quota. Usage and expiry can be checked outside MCP using authenticated GET /api/v1/account (this also consumes a call).

• 401: invalid/revoked key.
• 403: inactive/expired access.
• 404: no completed saved report for that query.
• 422: invalid parameters.
• 429: daily quota exhausted; see the HTTP API's Retry-After header.

The tools never change subscriptions, rotate keys, submit orders, or access a local product database. API calls require HTTPS except for local development; redirects are not followed with credentials. Keys are environment credentials, not tool inputs. Model inference runs in your MCP client; this adapter only retrieves research data.

Container option

A non-root container is included for directory safety/quality checks and clients that prefer Docker. Pass credentials at runtime; they are never baked into the image.

docker build -t capitol-ledger-mcp .
docker run --rm -i -e CAPITOL_LEDGER_API_KEY -e CAPITOL_LEDGER_API_URL capitol-ledger-mcp

Use -i for MCP stdio; do not allocate a TTY. Starting the server and listing its tools do not require a key, but data calls do.

Development

pip install -e '.[dev]'
pytest
ruff check .

Tests use mocked HTTP and do not need live credentials or consume API quota.

Publishing

See PUBLISHING.md for the release workflow, PyPI trusted publisher setup, and official MCP Registry metadata. Directory submissions are not evidence of endorsement or listing approval.

License and contact

MIT for the adapter code. Hosted API access and data rights are separate. Contact: [email protected].