Lawmesh MCP Server

A comprehensive Model Context Protocol (MCP) server providing AI agents with powerful tools to access U.S. legislative data through the OpenStates API v3.

Live Deployment

Public MCP Server: https://pk-dev-Lawmesh.hf.space/mcp

The server is deployed on Hugging Face Spaces and ready for immediate use with any MCP-compatible client.

Related MCP server: LegiScan MCP Server

Available Tools

Lawmesh provides four comprehensive tools for querying U.S. legislative information:

1. list_jurisdictions

Retrieve all available U.S. jurisdictions (states, territories, federal districts) with optional filtering.

Parameters:

• classification (optional): Filter by type ("state", "municipality", "country")

• include (optional): Additional data ("organizations", "legislative_sessions", "latest_runs")

• page, per_page: Pagination support

2. get_jurisdiction

Get detailed metadata for a specific jurisdiction.

Parameters:

• jurisdiction (required): State abbreviation, full name, or OpenStates ID

• include (optional): Additional data to include

3. get_people

Search for legislators, governors, and government officials.

Parameters:

• jurisdiction, name, id: Filter criteria (at least one required)

• org_classification: Role filter ("upper", "lower", "executive")

• district: District filter

• include: Additional biographical data

• Pagination support

4. get_bills

Search legislative bills, resolutions, and documents.

Parameters:

• jurisdiction, session, chamber: Basic filters

• identifier: Specific bill numbers

• classification: Bill type ("bill", "resolution")

• subject, sponsor: Content and sponsor filters

• q: Full-text search

• updated_since, created_since, action_since: Date filters

• include: Additional data (votes, actions, documents, etc.)

• sort: Sort options

• Pagination support

Architecture

Lawmesh is built using:

• FastMCP: Modern MCP server framework

• Streamable HTTP Transport: Optimized for web deployment

• OpenStates API v3: Authoritative source for U.S. legislative data

• Async Architecture: High-performance concurrent request handling

┌─────────────────┐    HTTP/MCP     ┌─────────────────┐    HTTPS/API    ┌─────────────────┐
│   MCP Client    │ <-------------> │  Lawmesh Server │ <-------------> │  OpenStates API │
│  (Claude, etc.) │                │   (FastMCP)     │                │      (v3)       │
└─────────────────┘                └─────────────────┘                └─────────────────┘

Quick Start with MCP Client

Example: Python MCP Client

import asyncio
from mcp import create_client_session
from mcp.client.transports.http import create_http_transport

async def main():
    # Connect to the deployed Lawmesh server
    transport = create_http_transport("https://pk-dev-Lawmesh.hf.space/mcp")
    
    async with create_client_session(transport) as session:
        # List available tools
        tools = await session.list_tools()
        print("Available tools:", [tool.name for tool in tools.tools])
        
        # Example: Get California jurisdictions
        result = await session.call_tool("list_jurisdictions", {
            "classification": "state",
            "per_page": 10
        })
        print("Jurisdictions:", result.content)
        
        # Example: Search for bills about education in California
        bills = await session.call_tool("get_bills", {
            "jurisdiction": "ca",
            "subject": "education",
            "per_page": 5
        })
        print("Education bills:", bills.content)

if __name__ == "__main__":
    asyncio.run(main())

Example: Using with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "lawmesh": {
      "url": "https://pk-dev-Lawmesh.hf.space/mcp"
    }
  }
}

Local Development Setup

Prerequisites

1. Python 3.13+

2. OpenStates API Key: Get one at OpenStates.org

3. Environment Setup

Installation

1. Clone the repository:

git clone <repository-url>
cd Lawmesh

2. Install dependencies:

# Using pip
pip install -r requirements.txt

# Or using uv (recommended)
uv sync

3. Environment Configuration: Create a .env file:

# .env
OPENSTATES_API_KEY=your_openstates_api_key_here

4. Run the server:

# Development mode
python app.py

# Or with uvicorn
uvicorn app:app --host 0.0.0.0 --port 7860 --reload

The server will be available at: http://localhost:7860/mcp

Local Testing

Test your local server with MCP Inspector:

npx @modelcontextprotocol/inspector http://localhost:7860/mcp

Docker Deployment

Using the included Dockerfile:

# Build the image
docker build -t lawmesh-mcp .

# Run with environment variable
docker run -p 7860:7860 -e OPENSTATES_API_KEY=your_key_here lawmesh-mcp

Docker Compose:

# docker-compose.yml
version: '3.8'
services:
  lawmesh:
    build: .
    ports:
      - "7860:7860"
    environment:
      - OPENSTATES_API_KEY=${OPENSTATES_API_KEY}
    env_file:
      - .env

Dependencies

Core dependencies from pyproject.toml:

• fastmcp>=2.12.3: MCP server framework

• httpx>=0.28.1: Async HTTP client for API calls

• uvicorn>=0.36.0: ASGI server

• python-dotenv>=1.1.1: Environment variable management

• mcp[cli]>=1.14.1: MCP protocol support

Security & Configuration

Environment Variables

API Key Security

• Never commit API keys to version control

• Use environment variables or secure secret management

• For Hugging Face Spaces: Configure as Repository Secrets

Use Cases

• Political Research: Track legislation and voting patterns

• Government Transparency: Access public legislative records

• Civic Engagement: Build tools for citizen participation

• Academic Research: Study U.S. political processes

• News & Media: Automated legislative monitoring

• Legal Research: Access bill text and legislative history

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Submit a pull request

License

This project is open source. Please check the LICENSE file for details.

Support

• Issues: Report bugs and feature requests via GitHub Issues

• Documentation: OpenStates API v3 docs at docs.openstates.org

• MCP Protocol: Learn more at modelcontextprotocol.io

Built with ❤️ using FastMCP and OpenStates API