Parliament MCP Server

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 Elasticsearch
• Elasticsearch: Document storage and search engine, setup to automatically embed documents and allow 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 11 tools to assist in parliamentary research:

1. search_constituency - Search for constituencies by name or get comprehensive constituency details by ID
2. get_election_results - Get election results for constituencies or specific members
3. search_members - Search for members of the Commons or Lords by various criteria
4. get_detailed_member_information - Get comprehensive member information including biography, contact, interests, and voting record
5. get_state_of_the_parties - Get state of the parties for a house on a specific date
6. get_government_posts - Get exhaustive list of all government posts and their current holders
7. get_opposition_posts - Get exhaustive list of all opposition posts and their current holders
8. get_departments - Get reference data for government departments
9. search_parliamentary_questions - Search Parliamentary Written Questions (PQs) by topic, date, party, or member
10. search_debates - Search through debate titles to find relevant debates
11. search_contributions - Search Hansard parliamentary records for actual spoken contributions during debates

Quick Start (local elasticsearch)

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 Elasticsearch database with some example data from June 2025.

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

Manual Setup

1. Clone, setup environment, and start services

Note on Elasticsearch Configuration

The system supports two methods for connecting to Elasticsearch:

1. Local/Self-hosted: Use ELASTICSEARCH_HOST, ELASTICSEARCH_PORT, and ELASTICSEARCH_SCHEME
2. Elasticsearch Cloud: Use ELASTICSEARCH_CLOUD_ID and ELASTICSEARCH_API_KEY (automatically configures host, port, and scheme)

The services will be available at:

• MCP Server: http://localhost:8080/mcp/
• Elasticsearch: http://localhost:9200

3. Initialize Elasticsearch and Load Data

2. Install 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

You can also generate this configuration automatically:

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 es_health # Check Elasticsearch health
4. Run the MCP server locally:
   make run_mcp_server # Or directly with uv: uv run parliament-mcp serve

Project Structure

CLI Commands

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

Data Structure

The system works with two main types of parliamentary documents:

Parliamentary Questions (Index: 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 (Index: 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 Elasticsearch with proper mappings

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

Daily Data Ingestion

To keep the data in Elasticsearch 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:

This runs the equivalent of:

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.

AWS EventBridge Cron

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

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:

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 Elasticsearch container must be running (docker compose up -d elasticsearch).
• 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.

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.

3. Configure the Lambda in AWS

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

• Use ELASTICSEARCH_HOST, ELASTICSEARCH_PORT, and ELASTICSEARCH_SCHEME to point to your elasticsearch cluster
• 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"

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:

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

Check Elasticsearch status:

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 Elasticsearch is running and accessible
• Verify network connectivity to Parliamentary APIs
• Use --ll DEBUG flag for detailed logging

Elasticsearch issues

• Verify inference endpoints are created: parliament-mcp init-elasticsearch
• Use https://elasticvue.com/ to inspect the Elasticsearch instance

Contributing

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

License

MIT License - see LICENSE file for details