uk-parliament-mcp-server

---

Overview

Westminster records from the official UK Parliament Bills, Members, Commons and Lords Votes, Hansard, Written Questions, and Committees APIs. Search parliamentary business, retrieve selected records and source links, and trace members, bills, votes, answers, and committee evidence across their distinct identifiers. Runs as a stdio process or a local Streamable HTTP server; no API key is required.

Tools

Tool	Description
ukparl_lookup_reference	Resolve filter IDs, identifier namespaces, and historical coverage guidance
ukparl_search_bills	Search bill summaries by title, House, session, sponsor, stage, and bill type
ukparl_get_bill	Retrieve bill details, stages, publications, amendments, and ping-pong motions
ukparl_search_members	Find current and former MPs and peers, including dated membership searches
ukparl_get_member	Retrieve profiles, roles, committee seats, official contacts, interests, and voting history
ukparl_search_divisions	Search House-scoped divisions and inspect metadata, voters, and party totals
ukparl_search_hansard	Search spoken contributions with complete source text where supplied
ukparl_search_questions	Search question and answer previews or retrieve complete question details
ukparl_get_committee	Discover committees and retrieve memberships, business, and publication metadata

Capability reference

ukparl_lookup_reference _tool

• topic: identifiers, coverage, bill_stages, bill_types, parties, departments, or answering_bodies; live directories default to 10 rows, capped at 20, with optional nameContains AND-token filtering
• house is required only for parties; that directory covers active parties in the selected House, not every historical party. Static guides accept neither House nor name filters
• Identifier guidance distinguishes reference stageId from bill-specific billStageId, House-scoped division IDs, Questions API IDs from UINs, and committee person IDs from Members API IDs

---

ukparl_search_bills _tool

• Optional query, house, sessionId, memberId, stageIds, and billTypeIds; each ID array accepts up to 20 entries. Defaults to 10 bills, capped at 20
• Results are detailLevel: "summary" with billId, provenance, and collection continuation; no current-session scope is inferred. Resolve reference filters with ukparl_lookup_reference

---

ukparl_get_bill _tool

• Required billId; section defaults to overview, or selects stages, stage, publications, amendments, amendment, motions, or motion. Collections default to 20 records, capped at 50
• Stage, amendment, and motion selections require the bill-specific billStageId from stages; singular amendment/motion retrieval also needs itemId from the parent collection (amendmentId for amendments, motion.id for motions). Amendment/motion lists are summaries; singular selectors retrieve complete text
• Missing entities return found: false with guidance. legislationHandoff.status is authoritative_link, not_enacted, or unavailable; only actual supplied legislation.gov.uk links establish a statute handoff

---

ukparl_search_members _tool

• Optional name, constituency (source location text), partyId, and house; currentOnly defaults to false, including current and former members. Defaults to 10 rows, capped at 20
• asOf selects membership on a real YYYY-MM-DD date and accepts only name and pagination alongside it; returned latest profile fields are not a historical snapshot
• Summary hits carry memberId for ukparl_get_member, source, and page; unknown source fields remain absent or null

---

ukparl_get_member _tool

• Required memberId; section: profile (default), roles, committee_seats, contact, interests, or voting. Roles without category returns an availability outline; select a returned category for whole role periods
• house is required for interests and voting, and omitted elsewhere. Local histories default to 20 rows, capped at 50; voting uses native 20-row pages regardless of limit
• found and guidance distinguish missing members and unavailable source collections. Interest trees and committee relationships retain source pointers; voting preserves recorded lobby and teller facts without inferring abstention or lifetime participation

---

ukparl_search_divisions _tool

• Required house: commons or lords; mode: search (default), detail, voters, or party_totals. Search accepts query, memberId, and inclusive startDate / endDate; defaults to 5 divisions, capped at 10
• Other modes require a divisionId from the same House. Voters default to 20 rows, capped at 50, with exact source party labels and lobby: Commons aye, no, not_recorded; Lords content, not_content
• Detail preserves headline counts and teller identities; partyTotals counts listed non-tellers and tellers separately. not_recorded is the source list, never an abstention claim; member searches include teller participation

---

ukparl_search_hansard _tool

• Optional query, memberId, house, inclusive startDate / endDate, and numeric debateSectionId; defaults to 5 contributions, capped at 20. Dates are YYYY-MM-DD, with no inferred window
• detailLevel: "complete" carries full source contribution text, including HTML; summary means the source supplied only a preview. Section filtering does not establish a complete debate transcript
• coverage reports historical limitations, including the 2004–2006 website warning; empty results do not prove no debate occurred. Narrow date windows after timeouts; use ukparl_lookup_reference with topic: "coverage" for archive guidance

---

ukparl_search_questions _tool

• mode: "search" (default) accepts query, memberId, house, up to 20 answeringBodyIds, answered, and inclusive tabledFrom / tabledTo / answeredFrom / answeredTo dates (YYYY-MM-DD). Defaults to 10 previews, capped at 20
• Search includes all sessions and withdrawn questions; omitted answered includes either state. mode: "detail" takes a returned questionId alone for complete question/answer HTML, corrections, and attachment metadata; a UIN is not a questionId
• Results distinguish detailLevel: "summary" from "complete"; detail misses return found: false with guidance. Attachments are links and metadata, not downloaded files

---

ukparl_get_committee _tool

• mode: "search" (default) accepts query and house (commons, lords, joint), default 10/cap 20. detail, members, inquiries, and publications require committeeId; nested collections default to 20/cap 50
• inquiry requires businessId; publication requires publicationId. businessId can also filter publications. membership selects all (default), current, or former in members mode; query in inquiries/publications requires at least two characters
• inquiries includes all committee business types, labelled by isInquiry. Records retain typed entities and sourcePath relationships; publications return evidence/report metadata and document links, without downloads or text extraction

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

UK Parliament-specific:

• Keyless, read-only access to seven official Westminster API origins; devolved legislatures are outside scope
• Separate identifier namespaces and explicit source selections, with no inferred current session or date window
• Shared per-origin backpressure, bounded retries, and a 45-second call deadline across related requests
• Historical coverage remains source-specific: the Hansard archive starts on 22 November 1803, the Spoken API minimum date is unknown, and no automatic historical-archive fallback is performed

Agent-friendly output:

• Provenance — source API, request URL, retrieval timestamp, and licence link accompany source records; applied reports effective selections and limits
• Whole-record pagination — page.returned, hasMore, and nextCursor describe actual emitted records, with total only when known. Repeat the same filters and effective limit when following a cursor
• Lossless large records — delivery: "full" | "outline" | "fragment" separates complete payloads from contentPage continuations. Repeat the original tool inputs plus each contentCursor, follow all outline entries and continuations, concatenate consecutive fragments before JSON-decoding once, and reconstruct the selected record before advancing collectionPage
• Explicit recovery — invalid_cursor restarts a selection; source_changed restarts content retrieval after an upstream revision. Search previews, missing records, and unavailable collections remain distinct

Getting started

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "uk-parliament-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/uk-parliament-mcp-server@latest"],
      "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "uk-parliament-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/uk-parliament-mcp-server@latest"],
      "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "uk-parliament-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/uk-parliament-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• Internet access to the official Parliament APIs; no API key is required.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/uk-parliament-mcp-server.git

2. Navigate into the directory:

cd uk-parliament-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env for transport, logging, or authentication overrides as needed

Configuration

Variable	Description	Default
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Initial HTTP server port; startup logs report the bound port after collision retries.	3010
MCP_HTTP_HOST	HTTP bind address.	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP MCP endpoint.	/mcp
MCP_SESSION_MODE	HTTP session mode: stateless, stateful, or auto.	stateless
MCP_AUTH_MODE	Authentication: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.).	info
LOGS_DIR	Directory for log files (Node.js only).	<app-root>/logs
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.	in-memory
OTEL_ENABLED	Enable OpenTelemetry.	false

See .env.example for the common framework overrides. There are no server-specific environment variables.

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Project structure

Directory	Purpose
src/mcp-server/tools/definitions	Nine tool definitions (*.tool.ts).
src/services/parliament-http	Fixed-origin transport, provenance, cursors, and lossless content delivery.
src/services/bills	Bill search, scrutiny records, publications, and reference directories.
src/services/members	Member discovery, profiles, biographies, interests, and voting history.
src/services/divisions	Commons/Lords division metadata and recorded voter collections.
src/services/hansard	Spoken contribution search and historical coverage metadata.
src/services/questions	Written question previews and complete question/answer records.
src/services/committees	Committee business, membership, publication metadata, and typed relationships.
tests/	Unit and integration tests, mirroring the src/ structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage
• Register new tools and resources in the createApp() arrays in src/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Contains Parliamentary information licensed under the Open Parliament Licence v3.0 where applicable. Personal data, parliamentary marks, and third-party rights are excluded; preserve the source's notices and check rights before reusing excluded material. This software is independent and does not imply parliamentary endorsement.