Content
# 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
```python
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:
```json
{
"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](https://openstates.org/api/)
3. **Environment Setup**
### Installation
1. **Clone the repository:**
```bash
git clone <repository-url>
cd Lawmesh
```
2. **Install dependencies:**
```bash
# Using pip
pip install -r requirements.txt
# Or using uv (recommended)
uv sync
```
3. **Environment Configuration:**
Create a `.env` file:
```bash
# .env
OPENSTATES_API_KEY=your_openstates_api_key_here
```
4. **Run the server:**
```bash
# 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:
```bash
npx @modelcontextprotocol/inspector http://localhost:7860/mcp
```
## Docker Deployment
### Using the included Dockerfile:
```bash
# 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:
```yaml
# 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](https://docs.openstates.org/api-v3/)
- **MCP Protocol**: Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io/)
---
**Built with ❤️ using FastMCP and OpenStates API**
