Us Lobbying MCP Server

@cyanheads/us-lobbying-mcp-server Search US lobbying disclosures and foreign-agent registrations via MCP. STDIO or Streamable HTTP. 9 Tools (+1 opt-in)

Public Hosted Server: https://us-lobbying.caseyjhand.com/mcp

---

Overview

US federal lobbying disclosures from the Senate's LDA API and foreign-agent registrations from the Department of Justice's FARA records. Search filings, resolve client relationships, inspect lobbyist and contribution disclosures, and analyze reported amounts with optional local SQL. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above; no API key required.

Tools

Capability reference

uslobbying_search_filings tool

• Supply at least one upstream filter: filing_uuid, filing_year (1999–current UTC year), client/registrant/lobbyist ID or name, filing_type, filing_period, specific_issues, posted_after / posted_before, amount_min / amount_max, client_state, client_country, foreign_entity_name, or foreign_entity_country. Dates are real YYYY-MM-DD calendar dates; amounts are exact decimal USD strings with at most two fractional digits and use native filing-filter semantics. Text is trimmed, blanks omitted, and state/country codes uppercased. Filters combine conjunctively; optional issue_code applies locally and cannot narrow upstream requests.
• Pass a filing_uuid from lobbyist evidence or analytical selections to retrieve the complete filing, including nested source fields and document links.
• Returns complete filings with amendment_policy: "all_versions", separate nullable USD decimal-string income / expenses, document links, and nested disclosures. Shared acquisition and record-window rules appear under Features.

---

uslobbying_get_client_profile tool

• mode: "resolve" (default) requires client_name; mode: "profile" requires explicit client_ids and years (1999–current UTC year). Pass each candidate's id, not its registrant-assigned client_id. IDs identify relationships with registrants; candidates are never automatically merged into a corporate identity.
• Profile returns status: "collecting" until acquisition completes, then typed annual_ledgers, selections, firms, issue_codes, targeted_entities, selected_filings, activities, and raw_filings across output windows. row_set_totals / row_set_offsets describe each list's delivery.
• Optional nonempty, unique row_sets selects which of those lists to deliver inline. Omission delivers every set; raw_filings always means every acquired version, including selected versions. Selection never limits acquisition, analysis, complete-set totals or SQL staging. Omitted sets remain available by restarting the same scope with another selection or querying staged tables. Continue with omitted or equivalent row_sets; changing the selection fails cursor_invalid. Offsets, handles and output_complete follow the selected stream; notices remain deliverable for every selection.
• Empty client/year partitions produce factual notices naming the selected ID and year; zero rows do not establish whether an ID is valid. Notices share bounded delivery windows and count in total_records and delivery counters, while row_set_totals counts domain rows only. Follow every cursor.
• With CANVAS_PROVIDER_TYPE=duckdb, the first completed-acquisition delivery window returns a dataset containing all acquired filings, selected filings, and selected activities. Its exact replay retains the dataset; later windows retain canvas_id, describe_tool, query_tool and table guidance without repeating schemas. Optional input canvas_id reuses an existing canvas; an expired token fails canvas_not_found.

---

uslobbying_get_issue_spending tool

• Requires issue_code and explicit years; optional client_id / registrant_id narrow upstream acquisition. All versions are acquired before latest-period selection and local issue filtering; broad scans can take hours.
• Returns the same collecting/final analytical lists, optional row_sets selection and dataset routing as profile mode, with attribution_basis: "whole_filing_mentions_issue". Whole-filing amounts overlap across issue buckets and are not allocated issue spending.

---

uslobbying_search_lobbyists tool

• mode: "search" (default) requires name, registrant_name, or registrant_id; mode: "activity" requires lobbyist_id and filing_year, with optional client_id and covered_positions_only.
• Returns identity lobbyists or filing-scoped evidence, including the matching participant, complete activity, original indexes, and filing UUID/document. Use that UUID with uslobbying_search_filings for the complete filing. Covered positions are disclosed text, not verified current employment.

---

uslobbying_get_contributions tool

• Requires filing_year (2008–current UTC year); optional filing_period (mid_year / year_end), registrant/lobbyist selectors, contribution_type, contributor, payee, honoree, inclusive contribution_date_after / contribution_date_before, and inclusive local item amount_min / amount_max decimal USD strings. Unknown item amounts cannot satisfy a bound. Contribution amount predicates run locally because native amount filters do not reliably select matching reports.
• Returns full parent reports, complete contribution_items, and matched_item_indexes where every child predicate matched the same item. Originals and amendments remain separate; report_count_in_batch and item_count_in_batch are not donation totals.

---

uslobbying_search_foreign_agents tool

• mode: "search" (default) searches daily XML snapshots; choose entity: "registrants" (default) or "foreign_principals", optional literal token-AND name_contains, and exact country labels for principals only. status is active (default), terminated, or all; principal status is independent of registrant status.
• mode: "detail" requires a digit-string registration_number and retrieves only the chosen live collection: foreign_principals (default), short_forms, or documents. Documents require status: "all" (the effective default for documents); an empty collection does not prove a registration never existed.
• page_size controls local windows over pinned results (default 25; larger positive integers clamp to 25); follow next_cursor. Responses retain source fields, official links, and snapshot retrieval metadata where applicable.

---

uslobbying_list_reference tool

• Start with topic: issue_codes, filing_types, government_entities, contribution_types, countries, identifiers, methodology, or fara_rules; optional filter applies literal case-insensitive token-AND matching.
• Returns attributed entries, total_entries, and matched_entries; follow next_cursor for pinned windows of up to 125 entries, or record_handles for oversized entries. Countries retain separately attributed LDA codes and FARA labels, without a guessed ISO mapping.

---

uslobbying_dataframe_query tool

• Requires canvas_id and either one read-only SELECT in sql (optional fresh register_as) or a stored result_table with optional offset. row_limit defaults to 25; larger positive integers clamp to 100, then any lower provider ceiling. The response byte budget may deliver fewer whole rows.
• New SQL materializes the complete result. Continue with result_table / next_offset; row_count is exact and row_order: "canonical_values" describes delivery ordering. Writes, multiple statements, external reads, and prohibited plan operators fail with typed reasons.
• A row that cannot fit fails query_row_too_large while retaining the materialization: select fewer columns or explicit SUBSTR windows. Missing/expired tables fail missing_table; SQL is unavailable without an enabled canvas.

---

uslobbying_dataframe_describe tool

• Requires a returned canvas_id; optional table_name selects one table. Inspect authoritative columns and types before SQL.
• Returns exact row counts, grain, creation/expiry, source tool, acquisition provenance, and materializing SQL where applicable. It does not enumerate other canvases.

---

uslobbying_dataframe_drop tool

• Requires canvas_id and table_name; idempotent, returning dropped: false for an absent table.
• Off unless USLOBBYING_DATAFRAME_DROP_ENABLED=true; when disabled it is absent from tools/list. This deletes local staged data only.

Features

Built on [@cyanheads/mcp-ts-core](https: