Skip to main content
Glama
joalbrecht

Capitol Ledger — Congressional Stock Disclosures

by joalbrecht
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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.

Related MCP server: ibkr-mcp

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: hello@capitol-ledger.com.

Available Tools

3 tools
get_portfolioA
Read-only

Get a saved synthetic disclosure ledger's opening/closing allocations and audit metadata.

Defaults to latest saved completed period, of any cadence. Pin report_id for reproducibility. This is not actual member holdings or the executable strategy portfolio.

NameRequiredDescriptionDefault
as_ofNo
report_idNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and non-destructive behavior, so the description correctly focuses on semantics: the default resolution rule (latest completed period, any cadence) and the warning that these are synthetic allocations, not real holdings. It does not mention pagination or sizing of the ledger, but the presence of an output schema covers return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the primary purpose, followed by the default-resolution rule and the disclaiming boundary. Each sentence adds distinct information and none repeats the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be described, and the description covers the key ambiguity (synthetic ledger vs. real holdings) plus the default period. Only the as_of input format and explicit routing against siblings are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning. It adds real value for report_id (the reproducibility pin) and implies as_of selects the period, but never specifies the accepted format of as_of (date string, date-range, period label), which is essential for a string-typed untyped param.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: retrieve the opening/closing allocations and audit metadata of a saved synthetic disclosure ledger. The closing disclaimer ('not actual member holdings or the executable strategy portfolio') draws a clear boundary, though sibling get_portfolio_changes is never mentioned by name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an implicit default ('latest saved completed period, of any cadence') and an instruction to pin report_id for reproducibility, which is useful. However, it never says when to call this rather than get_portfolio_changes or search_disclosures, so the agent is left to infer the choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_portfolio_changesB
Read-only

Get purchases, sales, and weight changes for a saved report period; inspect coverage warnings.

Pass the portfolio result's report_id to use exactly the same period.

NameRequiredDescriptionDefault
as_ofNo
report_idNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered externally. The description adds that coverage warnings are included and that report_id preserves the saved period, but it does not describe return format, limitations, or data coverage details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two focused sentences with no wasted text. The main purpose is front-loaded, and the second sentence gives a concrete usage instruction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema and annotations, reducing the description's burden. Still, for a 2-parameter tool with 0% schema description coverage, the description leaves as_of unexplained and does not clarify the choice between report_id and as_of.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for both parameters. It explains report_id's intended use for matching the portfolio report period, but it does not explain as_of at all, leaving one of two parameters undocumented in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it gets purchases, sales, and weight changes for a saved report period, and also surfaces coverage warnings. It is clear on its own, but it does not explicitly distinguish itself from sibling tools such as get_portfolio.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides useful usage context by saying to pass the portfolio result's report_id to reuse exactly the same period. However, it does not say when to choose this tool over get_portfolio or search_disclosures, nor does it explain when to use as_of instead of report_id.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_disclosuresA
Read-only

Search House disclosures; dates use filing availability. Return source links and amount ranges.

Default window is 30 days. Maximum limit is 100. Reuse returned as_of when paging. Timestamps must include a UTC offset; side is purchase, sale, or exchange.

NameRequiredDescriptionDefault
sideNo
as_ofNo
limitNo
offsetNo
tickerNo
available_afterNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already establish read-only, open-world, and non-destructive behavior. The description adds useful context: filing-availability-based dates, source links and amount ranges in results, default window, maximum limit, paging guidance, and timestamp format constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded: it names the resource, return shape, and key behavioral constraints in a few compact sentences. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The annotations and output schema reduce the need to explain safety and return values. Still, for a six-parameter search with 0% schema description coverage, the description leaves important input semantics partially unexplained, especially ticker and offset.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the full parameter burden. It explains side values, limit maximum, as_of paging reuse, and timestamp UTC offsets, but it never explains ticker or offset, and available_after is only indirectly touched.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Search House disclosures'. This is clearly distinct from the sibling portfolio tools, but it does not explicitly differentiate itself or state when to choose it over those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides operational details such as the default 30-day window, a maximum limit of 100, and reuse of as_of when paging. However, it does not explicitly say when to use this tool versus get_portfolio or get_portfolio_changes, nor does it describe exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedget_portfolio
    • First observedget_portfolio_changes
    • First observedsearch_disclosures
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 3 tools

Disambiguation4/5

get_portfolio and get_portfolio_changes both operate on saved report periods, but one returns allocations/audit metadata while the other returns purchases, sales, and weight changes. search_disclosures is clearly distinct. The boundary is mostly clear, with only mild potential confusion between the two portfolio tools.

Naming Consistency5/5

All tool names use snake_case verb_noun patterns: get_portfolio, get_portfolio_changes, and search_disclosures. The get/search variation is semantically appropriate and predictable.

Tool Count4/5

Three tools is on the lean side but reasonable for the apparent scope: retrieve a saved portfolio, inspect its changes, and search disclosures. Each tool earns its place, though the surface feels slightly minimal.

Completeness3/5

The set covers saved portfolio retrieval and House disclosure search, but notably omits Senate disclosures despite the 'Congressional' scope, and lacks operations for listing saved reports or fetching a specific disclosure/member detail. These gaps limit agent workflows that fall outside House disclosure search or existing saved reports.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • sc-mcp

    ratulotron
    A
    license
    B
    quality
    C
    maintenance
    A read-only MCP server that wraps the Scalable Capital CLI to expose broker data (portfolio, holdings, transactions, analytics, quotes, news) to any MCP-capable client.
    8
    MIT

  • ibkr-mcp

    christospappas
    A
    license
    A
    quality
    D
    maintenance
    A read-only MCP server that connects to Interactive Brokers Gateway or TWS to expose account, contract, execution, and historical-data queries over stdio.
    9
    14 npm
    MIT

  • Sarwa Tools

    manaskarra
    A
    license
    Not graded
    quality
    C
    maintenance
    An unofficial, read-only MCP server for Sarwa Odyssey that provides portfolio, holdings, transactions, watchlists, and agent snapshots via deterministic JSON documents.
    5 npm
    MIT

  • cairn

    arunash
    F
    license
    Not graded
    quality
    D
    maintenance
    A local-first MCP server that connects Claude Code to your Robinhood account, enabling read-only portfolio insights, tax analysis, and natural language queries, with optional human-in-the-loop trading actions.
    -