parliament-mcp

Parliament MCP Server

An MCP server that roughly maps onto a subset of https://developer.parliament.uk/, as well as offering additional semantic search capabilities.

Architecture

This project provides:

• MCP Server: FastMCP-based server
• Python package: A small python package for querying and loading parliamentary data from https://developer.parliament.uk/ into Qdrant
• Qdrant: Vector database for semantic search over Hansard and Parliamentary Questions data.
• Claude Integration: Connect to Claude Desktop via mcp-remote proxy

Features

MCP Tools Available

The MCP Server exposes 13 tools to assist in parliamentary research:

Members & Elections

1. get_election_results - Get election results for constituencies or specific members
2. search_members - Search for members of the Commons or Lords by various criteria (includes location/postcode search)
3. get_detailed_member_information - Get comprehensive member information including biography, contact, interests, voting record, and committee membership

Parliamentary Structure

4. get_state_of_the_parties - Get state of the parties for a house on a specific date
5. list_ministerial_roles - Get exhaustive list of all government or opposition posts and their current holders
6. get_departments - Get reference data for government departments

Committees

7. list_all_committees - List all parliamentary committees by status and house
8. get_committee_details - Get comprehensive committee information including members, publications, evidence, and upcoming events
9. get_committee_document - Retrieve committee documents including oral evidence, written evidence, and publications

Parliamentary Business

10. search_parliamentary_questions - Search Parliamentary Written Questions (PQs) by topic, date, party, or member
11. search_debate_titles - Search through debate titles to find relevant debates
12. find_relevant_contributors - Find members who have contributed most on specific topics
13. search_contributions - Search Hansard parliamentary records for actual spoken contributions during debates

Quick Start (local qdrant)

You will need

• Docker and Docker Compose
• Node.js (for mcp-remote)
• Claude Desktop (or another MCP client)
• Azure OpenAI account with API access

Create a .env file by copying the .env.example in the project root and replace the necessary variables.

After configuring your .env file, run the following command for a one shot setup of the MCP server and the Qdrant database with some example data from June 2025.

make dev_setup_from_scratch

Once this is run, you can connect to the MCP server using this config

# Add this to your Claude Desktop config, or another MCP client:
# On macOS Claude Desktop config is located at `~/Library/Application\ Support/Claude/claude_desktop_config.json`
{
  "mcpServers": {
    "parliament-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8080/mcp/", "--allow-http", "--debug"]
    }
  }
}

Manual Setup

1. Clone, setup environment, and start services

Note on Qdrant Configuration

The system supports connecting to Qdrant:

1. Local/Self-hosted: Use QDRANT_URL (defaults to localhost:6333)
2. Qdrant Cloud: Use QDRANT_URL and QDRANT_API_KEY for cloud deployments

# Clone the repo
git clone git@github.com:i-dot-ai/parliament-mcp.git
cd parliament-mcp

# Set up the environment and complete the .env file
cp .env.example .env
nano .env

# Start Qdrant and MCP server
docker-compose up --build

The services will be available at:

• MCP Server: http://localhost:8080/mcp/
• Qdrant: http://localhost:6333

3. Initialize Qdrant and Load Data

# Initialise Qdrant
docker compose exec mcp-server uv run parliament-mcp --log-level INFO init-qdrant

# Load 2025-06-23 to 2025-06-27 hansard data
docker compose exec mcp-server uv run parliament-mcp load-data hansard --from-date 2025-06-23 --to-date 2025-06-27

# Load 2025-06-23 to 2025-06-27 parliamentary questions
docker compose exec mcp-server uv run parliament-mcp --log-level WARNING load-data parliamentary-questions --from-date 2025-06-23 --to-date 2025-06-27

2. Install mcp-remote

npm install -g mcp-remote

3. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "parliament-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp/",
        "--allow-http",
        "--debug"
      ]
    }
  }
}

You can also generate this configuration automatically:

make mcp_claude_config

4. Restart Claude Desktop

Claude should now have access to the Parliament MCP tools.

Development

Prerequisites for Local Development

• Python >= 3.12
• uv (Python package manager)
• Docker and Docker Compose
• Node.js (for mcp-remote)

Local Development Setup

1. Install uv (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Clone and set up the project:

   git clone <repository>
   cd parliament-mcp
   
   # Install dependencies with uv
   uv sync --extra dev
   

3. Available Make commands:

   make install           # Install all dependencies
   make test              # Run tests
   make test_integration  # Run integration tests (slow on first run)
   make lint              # Check code formatting
   make format            # Format and fix code
   make safe              # Run security checks
   
   # Pre-commit hooks
   make pre-commit-install  # Install pre-commit hooks
   make pre-commit         # Run pre-commit on all files
   
   # Docker operations
   make run             # Start services with Docker Compose
   make stop            # Stop Docker services
   make logs            # View MCP server logs
   
   # Development helpers
   make mcp_test        # Test MCP server connection
   make qdrant_health   # Check Qdrant health
   

4. Run the MCP server locally:

   make run_mcp_server
   # Or directly with uv:
   uv run parliament-mcp serve
   

Project Structure

parliament-mcp/
├── parliament_mcp/           # Main Python package
│   ├── cli.py               # CLI interface
│   ├── models.py            # Data models
│   ├── mcp_server/          # MCP server implementation
│   │   ├── api.py           # Core API endpoints and search tools
│   │   ├── committees.py    # Committee-related tools and handlers
│   │   ├── members.py       # Member-related tools and handlers
│   │   ├── qdrant_query_handler.py # Qdrant search handlers
│   │   ├── main.py          # FastAPI application setup
│   │   └── utils.py         # Utility functions
│   └── ...                  # Other modules
├── tests/                   # Test suite
│   ├── mcp_server/          # MCP server tests
│   └── ...                  # Other tests
├── Dockerfile.mcp-server    # MCP server container configuration
├── docker-compose.yaml      # Service orchestration
└── README.md                # This file

CLI Commands

The project includes a unified CLI for data management and server operations:

# Initialize Qdrant collections
parliament-mcp init-qdrant

# Run the MCP server
parliament-mcp serve

# Load data with flexible date parsing
parliament-mcp load-data hansard --from-date "3 days ago" --to-date "today"
parliament-mcp load-data parliamentary-questions --from-date "2025-01-01"

# Delete all data
parliament-mcp delete-qdrant

Data Structure

The system works with two main types of parliamentary documents:

Parliamentary Questions (Collection: parliamentary_questions):

• Written Questions with semantic search on question and answer text
• Member information for asking and answering members
• Date, reference numbers, and department details

Hansard Contributions (Collection: hansard_contributions):

• Spoken contributions from parliamentary debates
• Semantic search on full contribution text
• Speaker information and debate context
• House (Commons/Lords) and sitting date

Data Loading Process:

1. Fetch from Parliamentary APIs (Hansard API, Parliamentary Questions API)
2. Transform into structured models with computed fields
3. Embed using Azure OpenAI for semantic search
4. Index into Qdrant with proper vector configurations

Data is loaded automatically from official Parliamentary APIs - no manual document creation needed.

Daily Data Ingestion

To keep the data in Qdrant up-to-date, a daily ingestion mechanism is provided. This loads the last two days of data from both hansard and parliamentary-questions sources.

To run the daily ingestion manually:

make ingest_daily

This runs the equivalent of:

parliament-mcp load-data hansard --from-date "2 days ago" --to-date "today"
parliament-mcp load-data parliamentary-questions --from-date "2 days ago" --to-date "today"

For automated daily ingestion, you can use a cron job. Here are examples for standard cron and AWS EventBridge cron.

Standard Cron

This cron job will run every day at 4am.

0 4 * * * cd /path/to/parliament-mcp && make ingest_daily

AWS EventBridge Cron

This AWS EventBridge cron expression will run every day at 4am UTC.

cron(0 4 * * ? *)

Notes on AWS Lambda Deployment for Daily ingestion

A docker based AWS lambda image is provided to run daily ingestion tasks.

1. Build the Lambda Container Image

Build the Docker image using the provided Makefile target:

make docker_build_lambda

This will create a Docker image named parliament-mcp-lambda:latest.

2. Test the Lambda locally

You can test the Lambda function locally using the AWS Lambda Runtime Interface Emulator (RIE), which is included in the base image.

Prerequisites:

• Your local Qdrant container must be running (docker compose up -d qdrant).
• The Lambda container image must be built (make docker_build_lambda).

Run the container:

A convenient way to provide the necessary environment variables is to use the --env-file flag with your .env file. You still need to override the ELASTICSEARCH_HOST to ensure the container can connect to the service running on your local machine.

docker run --rm -p 9000:8080 \
  --env-file .env \
  -e QDRANT_HOST="host.docker.internal" \
  parliament-mcp-lambda:latest

Trigger the function:

Open a new terminal and run the following curl command to send a test invocation. The from_date and to_date parameters are optional. If not provided, it will default to loading everything from the last 2 days.

curl -X POST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"from_date": "2025-06-23", "to_date": "2025-06-27"}'

3. Configure the Lambda in AWS

With the image pushed to ECR, you can create the Lambda with the following configurations

• Use QDRANT_HOST and QDRANT_PORT to point to your Qdrant instance
• Increase the default timeout to ~10 minutes to ensure the ingestion has enough time to complete
• Use AWS's flavour of cron to schedule the task for ~4am every day - cron(0 4 * * ? *)

• Remember to increase the default timeout to ~10 minutes to ensure the ingestion has enough time to complete.

Usage Examples

Once connected to Claude, you can use natural language queries like:

Parliamentary Questions:

• "Search for parliamentary questions about climate change policy"
• "Find questions asked by Conservative MPs about healthcare funding"
• "Show me recent questions about education from the last week"

Hansard Contributions:

• "Search for contributions about the budget debate"
• "Find speeches by Keir Starmer about economic policy"
• "Show me debates from the House of Lords about immigration"

Member Information:

• "Get detailed information about the MP for Birmingham Edgbaston"
• "Search for Labour MPs elected in 2024"
• "Find constituency information for postcode SW1A 0AA"

Parliamentary Structure:

• "Show me the current government ministers"
• "Get the state of the parties in the House of Commons"
• "List all opposition shadow cabinet positions"

Committees:

• "List all current Commons select committees"
• "Get details about the Public Accounts Committee including members and recent publications"
• "Show me oral evidence from the Treasury Committee"
• "Find committees dealing with environmental issues"

General Queries:

• "Search for debates about artificial intelligence regulation"
• "Find election results for marginal constituencies"
• "Show me government departments and their responsibilities"

Logs and Debugging

View server logs:

docker-compose logs mcp-server

Enable debug mode in Claude config by adding --debug flag.

Check Qdrant status:

curl http://localhost:6333/healthz
# Or use the make command:
make qdrant_health

Troubleshooting

Common Issues

MCP Connection Issues

• Ensure MCP server is running on port 8080
• The MCP server runs on /{MCP_ROOT_PATH}/mcp, not /MCP_ROOT_PATH
• Verify Claude Desktop configuration is correct

Data Loading Failures

• Check Azure OpenAI credentials in .env file
• Ensure Qdrant is running and accessible
• Verify network connectivity to Parliamentary APIs
• Use --ll DEBUG flag for detailed logging

Qdrant issues

• Verify collections are created: parliament-mcp init-qdrant
• Use the Qdrant Web UI at http://localhost:6333/dashboard to inspect collections

Contributing

Contributions are welcome! Please see our Contributing Guide for details on how to get started.

License

MIT License - see LICENSE file for details