Lawmesh 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.

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

Variable	Required	Description
OPENSTATES_API_KEY	Yes	Your OpenStates API key
PORT	No	Server port (default: 7860)
HOST	No	Server host (default: 0.0.0.0)

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