Skip to main content
Glama
LegiScan MCP Server

LegiScan MCP Server

by sh-patterson

LegiScan MCP 服务器

CI License: MIT Node TypeScript

一个模型上下文协议 (MCP) 服务器,为终端代理提供对 LegiScan API 的结构化访问,以获取美国所有 50 个州和国会的立法数据。

专为研究工作流构建,您可以指导代理(Codex、Claude Code、Claude Desktop 等)快速收集法案历史、提案人背景和投票记录。

功能

  • 10 个精简的 MCP 工具,针对立法研究工作流进行了优化

  • 复合工具,将多步研究工作流简化为单次 MCP 工具调用

  • 针对重复法案和点名投票查询的请求级批处理和查找缓存

  • 所有 API 响应的完整 TypeScript 类型定义

  • 法案编号标准化(处理 AB 858、AB858、AB-858 格式)

  • 针对州代码、立法者姓名查询和大型法案批次的输入验证护栏

Related MCP server: civic-awareness-mcp

安装

从 npm 安装(推荐)

npm install -g legiscan-mcp-server

从源码安装

git clone https://github.com/sh-patterson/legiscan-mcp.git
cd legiscan-mcp
npm install
npm run build

设置

1. 获取 LegiScan API 密钥

  1. 在 LegiScan 注册免费账户

  2. 在 https://legiscan.com/legiscan 注册 API 访问权限

  3. 复制您的 API 密钥

2. 添加到支持 MCP 的代理中

将此服务器添加到您的终端代理所使用的任何 MCP 主机中。

Claude Desktop 配置文件路径:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

对于其他 MCP 客户端(Codex CLI、Claude Code 等),请在相应客户端的 MCP 配置文件中添加相同的 mcpServers.legiscan 条目。

使用 npx(推荐)

{
  "mcpServers": {
    "legiscan": {
      "command": "npx",
      "args": ["-y", "legiscan-mcp-server"],
      "env": {
        "LEGISCAN_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用本地安装

{
  "mcpServers": {
    "legiscan": {
      "command": "node",
      "args": ["/path/to/legiscan-mcp-server/dist/index.js"],
      "env": {
        "LEGISCAN_API_KEY": "your_api_key_here"
      }
    }
  }
}

可用工具

复合工具(高阶研究)

工具

描述

legiscan_find_legislator

通过姓名查找立法者的 people_id。支持部分匹配。

legiscan_get_legislator_votes

在一次调用中获取立法者对多个法案的投票情况。

legiscan_get_primary_authored

仅获取立法者作为主要提案人(而非共同提案人)的法案。

法案

工具

描述

legiscan_get_bill

获取详细的法案信息(提案人、历史、投票、文本)

legiscan_find_bill_by_number

按编号查找法案(处理 AB 858、AB858、AB-858、A.B. 858)。最适合精确法案查找。

legiscan_get_roll_call

获取包含个人立法者投票详情的投票记录

人员

工具

描述

legiscan_get_person

获取包含第三方 ID(VoteSmart、OpenSecrets 等)的立法者信息

legiscan_get_session_people

获取某次会议中所有活跃的立法者

搜索

工具

描述

legiscan_search

对立法进行全文搜索。接受如 AB858 等法案编号变体,但对于精确匹配,请使用 legiscan_find_bill_by_number。

会议

工具

描述

legiscan_get_session_list

按州列出可用的立法会议

研究工作流(终端代理)

1. 从范围明确的请求开始

为您的代理提供目标、州、时间范围和输出格式。

示例提示词:

Use the LegiScan MCP tools to find major California housing bills in the current session.
Return: bill number, title, latest action date, top sponsors, and whether there was a close roll-call vote (margin <= 5).

2. 让代理遵循工具序列

为了获得高质量结果,请指示代理按此顺序操作:

  1. legiscan_get_session_list 以确定正确的会议。

  2. legiscan_search 或 legiscan_find_bill_by_number 以定位目标法案。

  3. legiscan_get_bill 以获取提案人/历史/投票参考。

  4. legiscan_get_roll_call 以获取个人投票详情。

  5. legiscan_get_person 仅在需要补充立法者信息时使用。

如果您从 legiscan_find_legislator 开始,请继续在后续的提案工作流中传递返回的 session.session_id 或相同的 state,以便结果保持在预期的立法机构和时间范围内。

3. 为分析师工作流重用复合工具

这些工具减少了工具调用量并简化了对代理的指令:

  • legiscan_find_legislator:从姓名查询中获取 people_id。

  • legiscan_get_primary_authored:将主要提案法案与共同提案法案分开。

  • legiscan_get_legislator_votes:在一次请求中拉取多个法案的投票立场。

提示词模板

A) 针对某位立法者的反对派研究

Use LegiScan MCP for Texas.
1) Find legislator "Jane Smith".
2) List all primary-authored bills in the current session.
3) For these bills, summarize topic area and latest status.
4) Then check votes on SB 12, HB 301, and SB 455, and show how the legislator voted.

B) 针对特定议题的法案追踪简报

Use LegiScan MCP to track "climate resilience" bills in New York.
Focus on current session only.
Return top 15 bills by relevance with bill number, title, last action, sponsor party, and any recorded roll calls.

C) 记分卡支持工作流

For California session 2172, resolve bill numbers AB 858, SB 525, SB 616, SB 399.
For each bill, fetch details and any roll calls.
Then report vote positions for people_id values 21719, 23214, and 25359.
Output as a table suitable for CSV export.

工作流简化

复合工具显著减少了常见工作流中代理与工具之间的往返次数:

工作流

手动 MCP 步骤

使用复合工具

获取 1 位立法者对 10 项法案的投票

查找立法者 → 搜索/解析法案 → 检查每项法案 → 检查每次点名投票

一旦拥有 bill_ids,只需 1 次工具调用

从 150 项提案法案中筛选主要提案

提案列表 → 获取每项法案 → 检查提案人

1 次工具调用,可选按 state 或 session_id 范围限定

按姓名查找立法者

会议发现 → 会议人员查找 → 手动匹配

1 次工具调用

研究技巧

  • 州代码被验证为双字母字符串并自动转换为大写(ca → CA)。无效代码(如 ZZ)可以通过本地验证,但会从 LegiScan 返回 API 错误。

  • 请务必在提示词中固定州和会议,以减少歧义结果。

  • 要求代理在中间输出中显示 bill_id、roll_call_id 和 people_id,以便您可以审计可追溯性。

  • 对于立法者搜索,请至少提供名字和姓氏(姓名输入必须至少为 2 个字符)。

  • legiscan_get_primary_authored 可以返回所有可用会议,但传递 state 或 session_id 可以使结果与预期的立法机构和时间范围保持一致。

  • legiscan_get_legislator_votes 每个请求最多接受 100 个 bill_ids;请将较大的任务拆分为多个块。

  • legiscan_search 会使用规范的空格格式重试紧凑的法案编号查询(如 AB858)。对于精确的法案解析,请优先使用 legiscan_find_bill_by_number。

  • 如果您计划进行后续分析,请要求以表格/CSV 格式输出最终结果。

开发

npm run build        # Compile TypeScript
npm run typecheck    # Type-check src + tests
npm test             # Run deterministic unit tests (no API key)
npm run test:e2e     # Run real-world workflow tests (skips cleanly without API key)
npm run test:live    # Run live API integration tests (requires API key)
npm run test:coverage # Run unit tests with coverage
npm run lint         # Check for lint errors
npm run format       # Format code with Prettier

测试模式

  • npm test / npm run test:unit:使用模拟网络调用的快速确定性测试。

  • npm run test:e2e:基于真实立法分析任务的研究工作流测试。如果 LEGISCAN_API_KEY 不可用,则跳过。

  • npm run test:live:真实的 LegiScan API 集成测试。需要 LEGISCAN_API_KEY。

API 限制

  • 免费公共 API 密钥每月有 30,000 次查询 的限制

  • 复合工具会批处理请求(最多 10 个并发)并在单个请求内缓存重复查找,以避免不必要的重复

  • 复合工具减少了 MCP 工作流的摩擦,但 LegiScan API 的使用量仍会随着您检查的不同法案和点名投票的数量而增加

Docker

在本地构建容器镜像:

docker build -t legiscan-mcp .

在运行时提供您的 API 密钥并运行它:

docker run --rm -i \
  -e LEGISCAN_API_KEY=your-api-key-here \
  legiscan-mcp

发布

Glama 检查需要 GitHub 发布。合并下一次仓库更改后,从 GitHub 创建并发布标签(例如 v1.0.0),或使用以下命令:

git tag v1.0.0
git push origin v1.0.0

Docker

在本地构建容器镜像:

docker build -t legiscan-mcp .

在运行时提供您的 API 密钥并运行它:

docker run --rm -i \
  -e LEGISCAN_API_KEY=your-api-key-here \
  legiscan-mcp

发布

Glama 检查需要 GitHub 发布。推送更改后,创建并发布标签(例如 v1.0.0)。

许可证

MIT - 详情请参阅 LICENSE。

Available Tools

10 tools
legiscan_find_bill_by_numberA

Find a bill by its number within a state's current session or specific session. Handles format variations (AB 858, AB858, AB-858). Returns bill summary if found, null if not.

Inputs: bill_number (required), state, session_id.

legiscan_find_legislatorA

Find a legislator's people_id by searching their name. Useful as a first step before other queries. Supports partial name matching.

Inputs: name (required), state (required), session_id.

legiscan_get_billA

Get detailed bill information including sponsors, full history, votes, texts, amendments, and supplements. This is the primary tool for bill research.

Inputs: bill_id (required).

legiscan_get_legislator_votesA

Get how a legislator voted on specific bills. Use find_legislator first to get people_id from a name. Returns vote positions (Yea/Nay/NV/Absent) for each bill with roll call details.

Inputs: bill_ids (required), people_id (required), chamber.

legiscan_get_personA

Get legislator information including party, role, district, and third-party IDs (VoteSmart, OpenSecrets, Ballotpedia, FollowTheMoney).

Inputs: people_id (required).

legiscan_get_primary_authoredA

Get only bills where a legislator is the PRIMARY author, not co-sponsor. Use find_legislator first to get people_id from a name. Filters out co-sponsored bills automatically.

Inputs: people_id (required), state, session_id.

legiscan_get_roll_callA

Get roll call vote details including individual legislator votes. Get roll_call_id by calling get_bill first.

Inputs: roll_call_id (required).

legiscan_get_session_listA

Get list of available legislative sessions. Returns sessions with session_id, years, and state info. Use session_id for subsequent bill lookups.

Inputs: state.

legiscan_get_session_peopleA

Get all legislators active in a legislative session. Returns list of people with their roles, parties, and districts.

Inputs: session_id (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action (bills, legislators, sessions, votes, search) with clear boundaries. Even related tools like get_legislator_votes and get_roll_call serve different purposes (individual legislator vs. specific roll call).

    Naming Consistency5/5

    All tool names follow a consistent 'legiscan_verb_noun' pattern using lowercase with underscores. Verbs are limited to 'find', 'get', and 'search', making the set predictable.

    Tool Count5/5

    10 tools is well-scoped for a legislative tracking server. Each tool addresses a core need without unnecessary duplication or omission.

    Completeness5/5

    The tool surface covers the primary lifecycle for legislative data: discovering sessions, searching bills, retrieving details, and accessing legislator info and votes. No obvious gaps for a read-only MCP server.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides tools to search and retrieve US federal and state legislative data, including bills, votes, campaign contributions, and legislator information, with provenance tracking.
      8
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Access U.S. state legislative data including bills, legislators, and votes across all 50 states via the OpenStates API.
      129 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying legislative data from the LegiScan API, including bills and votes, via natural language through an MCP gateway.
      260 npm
      MIT