Skip to main content
Glama
LegiScan MCP Server

LegiScan MCP Server

by sh-patterson

Servidor MCP de LegiScan

CI License: MIT Node TypeScript

Un servidor del Protocolo de Contexto de Modelo (MCP) que brinda a los agentes de terminal acceso estructurado a la API de LegiScan para obtener datos legislativos de los 50 estados de EE. UU. y el Congreso.

Creado para flujos de trabajo de investigación donde diriges a un agente (Codex, Claude Code, Claude Desktop, etc.) para recopilar rápidamente el historial de proyectos de ley, el contexto de los patrocinadores y los registros de votación.

Características

  • 10 herramientas MCP optimizadas para flujos de trabajo de investigación legislativa

  • Herramientas compuestas que condensan flujos de trabajo de investigación de varios pasos en llamadas a una sola herramienta MCP

  • Procesamiento por lotes por solicitud y almacenamiento en caché de búsqueda para consultas repetidas de proyectos de ley y votaciones nominales

  • Definiciones de tipo TypeScript completas para todas las respuestas de la API

  • Normalización de números de proyectos de ley (maneja formatos AB 858, AB858, AB-858)

  • Barreras de validación de entrada para códigos de estado, consultas de nombres de legisladores y grandes lotes de proyectos de ley

Related MCP server: civic-awareness-mcp

Instalación

Desde npm (Recomendado)

npm install -g legiscan-mcp-server

Desde el código fuente

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

Configuración

1. Obtén una clave de API de LegiScan

  1. Crea una cuenta gratuita en LegiScan

  2. Regístrate para obtener acceso a la API en https://legiscan.com/legiscan

  3. Copia tu clave de API

2. Añádelo a tu agente compatible con MCP

Añade este servidor a cualquier host MCP que utilice tu agente de terminal.

Rutas de configuración de Claude Desktop:

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

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

Para otros clientes MCP (Codex CLI, Claude Code, etc.), añade la misma entrada mcpServers.legiscan en el archivo de configuración MCP de ese cliente.

Usando npx (Recomendado)

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

Usando instalación local

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

Herramientas disponibles

Herramientas compuestas (Investigación de alto nivel)

Herramienta

Descripción

legiscan_find_legislator

Encuentra el people_id de un legislador por nombre. Admite coincidencias parciales.

legiscan_get_legislator_votes

Obtén cómo votó un legislador en múltiples proyectos de ley en una sola llamada.

legiscan_get_primary_authored

Obtén solo los proyectos de ley donde el legislador es el autor principal (no copatrocinador).

Proyectos de ley

Herramienta

Descripción

legiscan_get_bill

Obtén información detallada del proyecto de ley (patrocinadores, historial, votos, textos)

legiscan_find_bill_by_number

Encuentra un proyecto de ley por número (maneja AB 858, AB858, AB-858, A.B. 858). Ideal para búsquedas exactas.

legiscan_get_roll_call

Obtén detalles de la votación con los votos individuales de los legisladores

Personas

Herramienta

Descripción

legiscan_get_person

Obtén información del legislador con identificadores de terceros (VoteSmart, OpenSecrets, etc.)

legiscan_get_session_people

Obtén todos los legisladores activos en una sesión

Búsqueda

Herramienta

Descripción

legiscan_search

Búsqueda de texto completo en la legislación. Acepta variantes de números de proyectos de ley como AB858, pero usa legiscan_find_bill_by_number para coincidencias exactas.

Sesiones

Herramienta

Descripción

legiscan_get_session_list

Enumera las sesiones legislativas disponibles por estado

Flujo de trabajo del investigador (Agente de terminal)

1. Comienza con una solicitud delimitada

Dale a tu agente un objetivo, estado, marco temporal y formato de salida.

Ejemplo de prompt:

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. Pide al agente que siga una secuencia de herramientas

Para obtener resultados de alta calidad, dile al agente que siga este orden:

  1. legiscan_get_session_list para identificar la sesión correcta.

  2. legiscan_search o legiscan_find_bill_by_number para localizar los proyectos de ley objetivo.

  3. legiscan_get_bill para referencias de patrocinadores/historial/votos.

  4. legiscan_get_roll_call para detalles de votos individuales.

  5. legiscan_get_person solo cuando se necesite enriquecimiento de datos del legislador.

Si comienzas con legiscan_find_legislator, sigue pasando el session.session_id devuelto o el mismo state a los flujos de trabajo de autoría posteriores para que los resultados permanezcan en la legislatura y el marco temporal previstos.

3. Reutiliza herramientas compuestas para flujos de trabajo de analistas

Estas reducen el volumen de llamadas a herramientas y simplifican las instrucciones para tu agente:

  • legiscan_find_legislator: obtén people_id a partir de una consulta de nombre.

  • legiscan_get_primary_authored: separa los proyectos de ley de autoría principal de los copatrocinados.

  • legiscan_get_legislator_votes: extrae posiciones de voto en muchos proyectos de ley en una sola solicitud.

Plantillas de prompt

A) Investigación de oposición sobre un legislador

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) Resumen de seguimiento de proyectos de ley para un área temática

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) Flujo de trabajo de soporte para cuadros de mando (scorecards)

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.

Simplificación del flujo de trabajo

Las herramientas compuestas reducen drásticamente los viajes de ida y vuelta entre agente y herramienta para flujos de trabajo comunes:

Flujo de trabajo

Pasos manuales de MCP

Con herramientas compuestas

Obtener votos de 1 legislador en 10 proyectos de ley

Encontrar legislador → buscar/resolver proyectos → inspeccionar cada proyecto → inspeccionar cada votación

1 llamada a herramienta una vez que tengas los bill_ids

Filtrar autoría principal de 150 proyectos patrocinados

Lista de patrocinados → obtener cada proyecto → inspeccionar patrocinadores

1 llamada a herramienta, opcionalmente delimitada por state o session_id

Encontrar legislador por nombre

Descubrimiento de sesión → búsqueda de personas en sesión → coincidencia manual

1 llamada a herramienta

Consejos de investigación

  • Los códigos de estado se validan como cadenas de dos letras y se convierten automáticamente a mayúsculas (ca → CA). Los códigos no válidos como ZZ pasan la validación local pero devuelven un error de API de LegiScan.

  • Fija siempre el estado y la sesión en tu prompt para reducir resultados ambiguos.

  • Pide al agente que muestre bill_id, roll_call_id y people_id en la salida intermedia para que puedas auditar la trazabilidad.

  • Para la búsqueda de legisladores, proporciona al menos un nombre y un apellido (la entrada de nombre debe tener al menos 2 caracteres).

  • legiscan_get_primary_authored puede devolver todas las sesiones disponibles, pero pasar state o session_id mantiene los resultados alineados con la legislatura y el marco temporal previstos.

  • legiscan_get_legislator_votes acepta hasta 100 bill_ids por solicitud; divide los trabajos más grandes en fragmentos.

  • legiscan_search reintenta consultas compactas de números de proyectos de ley como AB858 usando un formato canónico con espacios. Para una resolución exacta de proyectos de ley, prefiere legiscan_find_bill_by_number.

  • Solicita las salidas finales en un formato de tabla o compatible con CSV si planeas realizar análisis posteriores.

Desarrollo

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

Modos de prueba

  • npm test / npm run test:unit: Pruebas deterministas rápidas con llamadas de red simuladas.

  • npm run test:e2e: Pruebas de flujo de trabajo de investigación basadas en tareas reales de análisis legislativo. Se omite si LEGISCAN_API_KEY no está disponible.

  • npm run test:live: Pruebas de integración de la API real de LegiScan. Requiere LEGISCAN_API_KEY.

Límites de la API

  • Las claves de API públicas gratuitas tienen un límite de 30,000 consultas por mes.

  • Las herramientas compuestas procesan solicitudes por lotes (máximo 10 concurrentes) y almacenan en caché las búsquedas repetidas dentro de una sola solicitud para evitar duplicaciones innecesarias.

  • Las herramientas compuestas reducen la fricción del flujo de trabajo MCP, pero el uso de la API de LegiScan sigue escalando con el número de proyectos de ley y votaciones distintas que inspecciones.

Docker

Construye la imagen del contenedor localmente:

docker build -t legiscan-mcp .

Ejecútalo con tu clave de API proporcionada en tiempo de ejecución:

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

Lanzamientos

Las comprobaciones de Glama esperan un lanzamiento de GitHub. Después de fusionar los cambios de tu repositorio, crea y publica una etiqueta como v1.0.0 desde GitHub o con:

git tag v1.0.0
git push origin v1.0.0

Docker

Construye la imagen del contenedor localmente:

docker build -t legiscan-mcp .

Ejecútalo con tu clave de API proporcionada en tiempo de ejecución:

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

Lanzamientos

Las comprobaciones de Glama esperan un lanzamiento de GitHub. Crea y publica una etiqueta como v1.0.0 después de enviar los cambios.

Licencia

MIT - consulta LICENSE para más detalles.

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