Documentation

Complete guide to Billy MCP Congressional Intelligence API

← Home Setup Guide Quick Start Tools Reference

📚 Table of Contents

🚀 Getting Started

🔧 Tools Categories

📊 Advanced Features

📖 Resources

🏛️ Overview

Billy MCP is the most comprehensive Congressional Intelligence API available, providing real-time access to all aspects of the U.S. Congress through the Model Context Protocol (MCP). Built specifically for AI assistants like Claude, Billy MCP transforms raw congressional data into actionable intelligence.

40+ Congressional Tools
5K API Requests/Hour
100% Real-time Data
Free Congress.gov API
🎯 What makes Billy MCP unique:
  • Natural language queries with AI-enhanced political analysis
  • Real-time congressional data with zero delays
  • Built specifically for Claude Desktop integration
  • Your own API keys - no server costs or quotas
  • Comprehensive coverage: bills, amendments, votes, members, and more

✨ Key Features

🧠 AI-Enhanced Analysis

Every tool provides AI-powered insights including political context, bipartisan analysis, passage probability assessment, and strategic implications.

🔄 Real-Time Data

Direct connection to Congress.gov API ensures you always have the latest information on bills, votes, amendments, and congressional activities.

🎯 Natural Language Queries

Ask questions in plain English: "What climate bills were introduced this week?" or "Show me bipartisan infrastructure amendments."

🔒 Privacy First

Use your own Congress.gov API key. No data passes through third-party servers except the official government API.

📦 Installation

Prerequisites

Step 1: Download Billy MCP

git clone https://github.com/deeployeer/billy-mcp.git cd billy-mcp npm install

Step 2: Configure Claude Desktop

Edit your Claude Desktop configuration file:

{ "mcpServers": { "billy": { "command": "node", "args": ["/full/path/to/billy-mcp/mcp-client.js"], "env": { "MCP_SERVER_URL": "https://mcp.billy.wiki", "CONGRESS_API_KEY": "your_congress_api_key_here" } } } }
📍 Configuration File Locations:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop to load Billy MCP. You should see a hammer icon 🔨 indicating MCP tools are available.

🚀 Quick Start

Once installed, you can immediately start asking Claude about congressional activities. Here are some example queries to get you started:

📋 Bill Research

Query: "What infrastructure bills were introduced this month?"

Billy MCP: Searches recent bills, analyzes political context, and provides passage probability assessments.

🗳️ Voting Analysis

Query: "Show me recent House votes on climate policy"

Billy MCP: Finds relevant votes, analyzes party-line patterns, and identifies bipartisan support.

👥 Member Profiles

Query: "Who are the senators from California and what are their key policy focuses?"

Billy MCP: Provides detailed member profiles with legislative priorities and influence analysis.

🔍 Amendment Tracking

Query: "Find amendments about healthcare reform in the current Congress"

Billy MCP: Searches amendments, analyzes sponsor patterns, and tracks legislative progress.

📋 Bills Tools (8 tools)

Comprehensive bill analysis with political context and AI-enhanced insights.

search_bills
🏛️ Natural language bill search with political analysis. Find bills using natural language queries with AI-enhanced political context and passage probability assessment.
get_bill_details
📊 Comprehensive bill analysis with stakeholder mapping. Get detailed information including political context, sponsor analysis, and AI-powered insights.
get_bill_actions
⚖️ Legislative timeline with momentum analysis. Track bill progress with AI-powered momentum assessment and bottleneck identification.
get_bill_text
📄 Full bill text with content analysis. Retrieve complete text with AI-powered complexity assessment and key terms extraction.
get_bill_cosponsors
🤝 Bipartisan coalition analysis. Analyze cosponsors with geographic distribution, party dynamics, and bipartisan index calculations.
get_bill_committees
🏛️ Committee jurisdiction analysis. Identify committees reviewing the bill and analyze legislative pathway with decision maker identification.
get_bill_subjects
🏷️ Policy categorization analysis. Get bill policy subjects with trend analysis and policy area connections.
get_bill_summaries
📋 Professional summaries with insights. Get official CRS summaries with AI-enhanced policy implications and strategic analysis.

Example Usage

"Find recent infrastructure bills and analyze their chances of passage"

This query will use search_bills to find infrastructure-related legislation, then automatically gather details, analyze cosponsorship patterns, and assess political momentum.

🔍 Amendments Tools (4 tools)

Deep amendment analysis with sponsor patterns and legislative strategy insights.

search_amendments
🔍 Intelligent Amendment Search. Find congressional amendments using natural language queries, political topics, or sponsor names with AI-powered political analysis.
get_amendment_details
📋 Deep Amendment Analysis. Get comprehensive information including sponsor details, legislative history, and political context with strategic insights.
get_amendment_text
📄 Amendment Text Retrieval. Get full legal text for detailed content analysis, legal research, and policy comparison with AI-enhanced analysis.
get_amendment_actions
⚖️ Legislative History Tracker. Get complete timeline of actions, votes, and procedural moves with parliamentary analysis.

👥 Members Tools (4 tools)

Congressional member profiles with influence analysis and legislative focus tracking.

search_members
👥 Congressional Members Search. Find current and former members with analysis of party distribution, state representation, and political profiles.
get_member_details
👤 Congressional Member Profile. Get comprehensive information including political profile, influence level, committee assignments, and legislative focus.
get_member_sponsored_legislation
📝 Member Sponsored Legislation. Get bills sponsored by a member with analysis of policy focus areas, success rates, and strategic approach.
get_member_cosponsored_legislation
🤝 Member Cosponsored Legislation. Get bills cosponsored by a member with analysis of collaboration patterns and bipartisan engagement.

🗳️ Votes Tools (3 tools)

House voting records with bipartisan analysis and political dynamics assessment.

search_house_votes
🗳️ House Roll Call Votes Search. Find House voting records with analysis of bipartisan patterns, party-line votes, and legislative outcomes.
get_house_vote_details
🗳️ House Vote Analysis. Get detailed information about specific votes including political significance and bipartisanship assessment.
get_house_vote_members
👥 House Vote Member Positions. Get detailed breakdown of how each member voted with party cohesion and crossover voting analysis.

📚 Congressional Record Tools (3 tools)

Speech and debate analysis with discourse patterns and rhetorical assessment.

search_congressional_record
📚 Speech and debate search with discourse analysis. Find congressional speeches with AI-powered speaker analysis and rhetorical pattern identification.
get_congressional_record_details
📖 Detailed record analysis with historical context. Get comprehensive information about specific entries with parliamentary context and historical significance.
get_congressional_record_text
📝 Full text with rhetorical analysis. Retrieve complete text with AI-powered speech pattern analysis and policy position extraction.

🎖️ Nominations Tools (3 tools)

Presidential nominations with confirmation analysis and Senate advice/consent tracking.

search_nominations
🎖️ Presidential Nominations Search. Find nominations with analysis of confirmation status, position types, and Senate advice/consent process.
get_nomination_details
📋 Presidential Nomination Analysis. Get comprehensive information including significance assessment, confirmation prospects, and nominee details.
get_nomination_actions
⚖️ Nomination Process Tracker. Get complete timeline with process stage analysis, committee path, and confirmation momentum.

🌍 Treaties Tools (4 tools)

International treaties with diplomatic significance and geopolitical context analysis.

search_treaties
🌍 International Treaties Search. Find treaties with analysis of diplomatic significance, ratification status, and geopolitical context.
get_treaty_details
📜 Treaty Analysis. Get comprehensive information including diplomatic context, ratification process, and international relations impact.
get_treaty_text
📄 Treaty Text Retrieval. Get complete legal text for detailed content analysis, legal research, and diplomatic review.
get_treaty_actions
⚖️ Treaty Process Tracker. Get complete timeline including ratification process, Senate procedures, and diplomatic milestones.

📖 CRS Reports Tools (3 tools)

Congressional Research Service reports with policy analysis and research insights.

search_crs_reports
🔍 Congressional Research Service Report Search. Find CRS reports by topic with analysis of congressional priorities and policy research.
get_crs_report_details
📋 Detailed CRS Report Analysis. Get comprehensive information including analysis and policy implications from expert research.
get_crs_report_text
📄 CRS Report Full Text. Access complete text for detailed content analysis and research insights.

📤 Communications Tools (4 tools)

Executive communications and legislative correspondence with constitutional analysis.

search_house_communications
🏛️ House Communications Search. Find executive communications and presidential messages with analysis of executive-legislative interactions.
get_house_communication_details
📄 House Communication Analysis. Get detailed information with strategic analysis and policy impact assessment.
search_senate_communications
🏛️ Senate Communications Search. Find executive communications with analysis of constitutional functions and executive-legislative relations.
get_senate_communication_details
📄 Senate Communication Analysis. Get detailed information with constitutional protocol analysis and Senate advice/consent context.

💡 Advanced Usage Examples

🔍 Multi-Tool Analysis

Query: "Analyze the Infrastructure Investment and Jobs Act - show me the bill details, voting record, and key amendments"

Billy MCP Response: Automatically uses multiple tools (bill search, details, actions, amendments) to provide comprehensive analysis including political momentum, bipartisan support patterns, and key policy modifications.

📊 Trend Analysis

Query: "What are the trending policy topics in Congress this month based on introduced bills and floor speeches?"

Billy MCP Response: Combines bill searches with Congressional Record analysis to identify emerging policy trends and political priorities.

🗳️ Voting Pattern Analysis

Query: "Show me voting patterns on climate legislation - which Republicans have crossed party lines?"

Billy MCP Response: Searches relevant votes, analyzes member positions, and identifies bipartisan coalitions with geographic and political context.

🔧 Troubleshooting

Common Issues

Issue Solution
"Cannot find module" error Run npm install in the billy-mcp directory
"MCP_SERVER_URL is required" Check your Claude Desktop config file syntax and server URL
"CONGRESS_API_KEY is required" Verify your API key at api.congress.gov and check config
"Failed to connect to server" Check internet connection and verify server URL is accessible

Getting Help

📚 API Reference

Server Information

Required Environment Variables

Variable Description Required
MCP_SERVER_URL Billy MCP server URL Yes
CONGRESS_API_KEY Your Congress.gov API key Yes
DEFAULT_CONGRESS Fallback Congress API key No
🔒 Privacy & Security:

Billy MCP uses your own API keys and connects directly to official government APIs. No congressional data passes through third-party servers except the official Congress.gov API.