home / mcp / openstates mcp server

OpenStates MCP Server

MCP Server generated by mcp.ag2.ai

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ag2-mcp-servers-open-states-api-v3": {
      "url": "https://api.apis.guru/v2/specs/openstates.org/2021.11.12/openapi.json",
      "headers": {
        "CONFIG": "{...}",
        "SECURITY": "API_KEY=YOUR_API_KEY",
        "CONFIG_PATH": "mcp_server/mcp_config.json"
      }
    }
  }
}

You run an MCP server that exposes a remote MCP endpoint and/or a local process you invoke, enabling clients to interact with the OpenStates data model through the MCP protocol. This server provides a standardized way for clients to discover, query, and subscribe to state data while keeping a clean separation between the data source and its consumers.

How to use

You can connect an MCP client to the server in two main ways: use the remote HTTP endpoint to run the MCP through a centralized server, or start a local process that communicates via stdio. Once connected, your client can perform operations such as requesting context data, subscribing to updates, and invoking available actions exposed by the MCP implementation. For best results, run the server with the provided command and ensure your client points to the correct endpoint or stdio channel. If you choose the HTTP method, supply the server URL as the endpoint you query. If you choose stdio, your client should establish a local IPC channel with the Python-based MCP server process.

How to install

# Prerequisites
Python 3.9+
pip and uv (uv is a lightweight runner you can use for Python development)

# Step 1: Clone the project
git clone <repository-url>
cd mcp_server

# Step 2: Install dependencies
# If you are using the development container, dependencies are installed via:
pip install -e ".[dev]"
# If you are not using the dev container, run the same command manually:
# pip install -e ".[dev]"
# Alternatively, you can use uv to run the editable install:
uv pip install --editable ".[dev]"
```

```sh
# Step 3: Run the server in stdio mode
python mcp_server/main.py stdio
```

# Optional: Verify environment variables for configuration
# CONFIG_PATH points to a JSON configuration file, if you use a file-based setup
# CONFIG can contain a JSON string with the configuration
# SECURITY can hold API keys or other security parameters

Configuration and startup notes

The server can be configured by providing a JSON configuration file or a JSON string via environment variables. The commonly used environment variables include CONFIG_PATH, CONFIG, and SECURITY. When starting in stdio mode, the server is executed with a Python command that launches the main entry point and specifies the mode. If you need to customize security parameters or supply a pre-defined configuration, use the CONFIG_PATH or CONFIG variables as described above.

Development and testing notes

# Linting and formatting
ruff check
ruff format

# Static analysis
./scripts/static-analysis.sh

# Run tests with coverage
./scripts/test.sh
./scripts/test-cov.sh
```

```sh
# Pre-commit hooks (install once per workstation)
pre-commit install

Available tools

lint

Check code quality and style using linting tools to ensure consistency across the project.

format

Format code according to project standards to improve readability and reduce diffs.

static-analysis

Run static analysis tools to detect potential security and reliability issues.

testing

Execute unit and integration tests with coverage reporting to validate behavior.