MCP 服务器

Lawmesh MCP Server

Enables AI agents to query U.S. legislative data, including jurisdictions, legislators, and bills, via the OpenStates API.

README

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.

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

Python 3.13+
OpenStates API Key: Get one at OpenStates.org
Environment Setup

Installation

Clone the repository:

git clone <repository-url>
cd Lawmesh

Install dependencies:

# Using pip
pip install -r requirements.txt

# Or using uv (recommended)
uv sync

Environment Configuration: Create a .env file:

# .env
OPENSTATES_API_KEY=your_openstates_api_key_here

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