Mcp Congress Gov Server

Congress.gov API MCP Server

This is a Model Context Protocol (MCP) server designed to provide access to the official Congress.gov API (v3) using a hybrid approach:

• MCP Resources: For direct lookups of core legislative entities (Bills, Members, Congresses, Committees, general Info) using standardized URIs.
• MCP Tools: For more complex operations like searching across collections (congress_search) and retrieving related data lists (congress_getSubResource).

This server acts as a bridge, allowing MCP clients (like AI assistants or development tools) to easily query and utilize U.S. legislative data.

Project Structure

• /src: Contains all source code.
• /config: Configuration management (ConfigurationManager.ts).
• /services: Core logic for interacting with Congress.gov API (CongressApiService.ts, RateLimitService.ts).
• /tools: MCP tool definitions (search/, subresource/, index.ts).
• /types: TypeScript interfaces and Zod schemas.
• /utils: Shared utility functions (logging, errors, etc.).
• resourceHandlers.ts: Logic for handling core entity resource requests.
• createServer.ts: Server instance creation, resource and tool registration.
• server.ts: Main application entry point.
• /dist: Compiled JavaScript output (generated by npm run build).
• /docs: Project documentation (PRD, Feature Spec, RFCs).
• package.json: Project metadata and dependencies.
• tsconfig.json: TypeScript compiler options.
• .eslintrc.json, .prettierrc.json: Linting and formatting rules.
• .env: (Not committed) For storing CONGRESS_GOV_API_KEY.

Getting Started

1. Install Dependencies:

``bash npm install ``

1. Set API Key: Create a .env file in the project root and add your Congress.gov API key:

`` CONGRESS_GOV_API_KEY=YOUR_API_KEY_HERE ``

(Get a key from https://api.data.gov/signup/)

1. Build the Server:

``bash npm run build ``

1. Run the Server:

``bash npm start ``

(This runs node dist/server.js)

Alternatively, run in development mode using npm run dev (uses ts-node and nodemon).

Usage with MCP Client

Connect your MCP client to the running server (e.g., via stdio if running locally).

Accessing Resources

Use the access_mcp_resource command/method with the appropriate URI.

Examples:

• Get Bill H.R. 3076 (117th Congress):

```

congress-server congress-gov://bill/117/hr/3076

```

• Get Member Pelosi:

```

congress-server congress-gov://member/P000197

```

• Get Info about 118th Congress:

```

congress-server congress-gov://congress/118

```

• Get API Overview:

```

congress-server congress-gov://info/overview

```

Using Tools

Use the use_mcp_tool command/method.

!!! CRITICAL TOOL WORKFLOW: Finding Entities & Getting Related Data !!!

Many common tasks require a mandatory two-step process using both tools:

1. STEP 1: Find the Entity ID using congress_search

• Purpose: Locate the specific bill, member, committee, etc., you need and extract its unique identifier(s) (e.g., memberId, or the congress, billType, billNumber for a bill URI).
• Tool: congress_search
• Example: Find member "John Kennedy" (might return multiple results requiring selection):

```xml

congress-server congress_search

{ "collection": "member", "query": "John Kennedy" }

```

• Output: Look for the memberId (e.g., K000393) or other necessary identifiers in the results.
• !!! WARNING !!! Searching might return multiple results. You MUST identify the correct entity and use its specific ID for the next step.
• !!! API LIMITATION !!! Filtering general searches by congress using the filters parameter is NOT SUPPORTED by the underlying API (e.g., for /v3/bill or /v3/member) and will be ignored. Congress-specific filtering usually requires using specific API paths (e.g., /v3/bill/117), which this tool does not construct.

1. STEP 2: Get Related Data using congress_getSubResource

• Purpose: Use the identifier(s) found in Step 1 to construct the parentUri and fetch related details (actions, sponsors, text, etc.).
• Tool: congress_getSubResource
• Prerequisite: You MUST have the correct parentUri (e.g., congress-gov://member/K000393) from Step 1.
• Example: Get legislation sponsored by member K000393:

```xml

congress-server congress_getSubResource

{ "parentUri": "congress-gov://member/K000393", "subResource": "sponsored-legislation", "limit": 5 }

```

• !!! GUARANTEED ERROR WARNING !!! You MUST use a subResource string that is STRICTLY VALID for the parentUri type (e.g., 'sponsored-legislation' for members, 'actions' for bills). Providing an invalid combination WILL cause an error. Check the tool description for valid combinations.

Following this two-step process is ESSENTIAL for reliably getting related information.

Tool Examples:

• Search for Bills containing "climate" (limit 5):

```xml

congress-server congress_search

{ "collection": "bill", "query": "climate", "limit": 5 }

```

• List Members (No Congress Filter Possible Here):
• Note: As mentioned above, filtering by congress directly in congress_search is not supported by the API for the 'member' collection.

```xml

congress-server congress_search

{ "collection": "member", "limit": 10 // Add "query" or other filters like "type" if needed }

```

• Get Actions for Bill H.R. 3076 (117th) (Requires URI from Search or Known Info):

```xml

congress-server congress_getSubResource

{ "parentUri": "congress-gov://bill/117/hr/3076", "subResource": "actions", "limit": 10 }

```

• Get Legislation Sponsored by Member P000197:

```xml

congress-server congress_getSubResource

{ "parentUri": "congress-gov://member/P000197", "subResource": "sponsored-legislation", "limit": 5 }

```

Linting and Formatting

• Lint: npm run lint
• Format: npm run format

Code will be automatically linted and formatted on commit via Husky and lint-staged.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bsmi021
• Source: bsmi021/mcp-congressgov_server
• License: MIT

Install and usage instructions live in the source repository linked above.