Uk Parliament Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.1.2Updated Oct 26, 2026

Search UK Parliament bills, members, votes, Hansard, written questions, and committees.

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingKnowledge & Memory

Overview

AI-generated overview

Read-only MCP server for UK Parliament data: search bills, MPs and peers, Commons and Lords votes, Hansard, written questions and committees.

What you can do
  • Search and retrieve bills, including stages, publications, amendments and motions
  • Find current and former MPs and peers, and read profiles, roles, committee seats, contacts, interests and voting history
  • Search Commons and Lords divisions, with detail, voter lists and party totals
  • Search spoken Hansard contributions and written questions, with full text where the source supplies it
  • Discover committees and their business, memberships, publications and written or oral evidence
  • Resolve filter IDs, identifier namespaces and historical coverage guidance
When to use it
Useful when you need to research Westminster proceedings, track a bill's progress, check how a member voted, or pull question and committee material without writing API code. It is aimed at research and journalism-style lookups rather than devolved legislatures, which are out of scope.
Requirements
Either the public hosted endpoint or a local process via npx (Node.js v24+ or Bun v1.4.0+), with internet access to the official Parliament APIs. No API key is required. Optional environment variables cover transport, HTTP host, port, endpoint path, log level, auth mode and storage.
Before you install
Read-only, but results are source data: names, HTML, answers and contributions should be treated as content, not instructions. Search hits are summaries, and empty results do not prove nothing happened, especially for Hansard 2004-2006. Do not infer a statute identifier from a bill title. Parliamentary information is under the Open Parliament Licence; personal data and third-party rights are excluded.

Installation

In SourceWeft

  1. Open Uk Parliament Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fuk-parliament-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "uk-parliament": {
      "type": "http",
      "url": "https://uk-parliament.caseyjhand.com/mcp"
    }
  }
}

README

@cyanheads/uk-parliament-mcp-server

Search UK Parliament bills, members, votes, Hansard, written questions, and committees via MCP. STDIO or Streamable HTTP.

9 Tools

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 publications across their distinct identifiers. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above; no API key is required.

Tools

ToolDescription
ukparl_lookup_referenceResolve filter IDs, identifier namespaces, and historical coverage guidance
ukparl_search_billsSearch and order bill summaries by title, House, session, sponsor, department, stage, type, and status
ukparl_get_billRetrieve bill details, stages, publications, amendments, and ping-pong motions
ukparl_search_membersFind current and former MPs and peers, including dated membership searches
ukparl_get_memberRetrieve profiles, roles, committee seats, official contacts, interests, and voting history
ukparl_search_divisionsSearch House-scoped divisions and member votes; inspect metadata, voters, and party totals
ukparl_search_hansardSearch spoken contributions with complete source text where supplied
ukparl_search_questionsSearch question and answer previews or retrieve complete question details
ukparl_get_committeeDiscover committees and business; retrieve memberships, publications, and written/oral evidence 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
  • departments IDs feed ukparl_search_bills.departmentId; they are distinct from Written Questions answering-body IDs

ukparl_search_bills tool

  • Optional query, current house, originatingHouse, sessionId, memberId, departmentId, stageIds, and billTypeIds; each ID array accepts up to 20 entries. Defaults to 10 bills, capped at 20
  • sortOrder: TitleAscending, TitleDescending, DateUpdatedAscending, or DateUpdatedDescending; omission preserves source ordering. Optional isDefeated and isWithdrawn accept true or false. inAmendableStage: true restricts to amendable stages; false leaves results unrestricted
  • 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
  • Only section: "amendments" accepts amendmentNumber (a string retaining letter suffixes), official decision, and sponsoring memberId filters. Filters apply before source pagination; singular retrieval still uses itemId
  • Missing entities return found: false with guidance. section: "publications" derives legislationHandoff (authoritative_link, not_enacted, or unavailable) from the bill's published documents; only supplied legislation.gov.uk links establish a statute handoff
  • Overview reads metadata only. Unless isAct is explicitly false, its unavailable handoff explains that publications remain unchecked; repeat with the same billId and section: "publications" to discover statute links

ukparl_search_members tool

  • Optional name, constituency (source location text: constituency name or postcode), 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 name, pagination, and currentOnly: false 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
  • Search with memberId returns memberVote: { memberId, lobby, wasTeller } on each result, using the House's recorded lobby. A missing result does not imply abstention

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, uin, asking-member memberId, answeringMemberId, 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
  • uin retains leading zeros and normalizes the HL prefix. Without dates, reused UINs can return candidates across sessions; combine tabledFrom / tabledTo and House filters to narrow them, then retrieve a returned 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, house (commons, lords, joint), and status: Current|Former|All, default 10/cap 20. detail, members, and publications require committeeId; inquiries accepts it optionally for committee-specific or cross-committee discovery. 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 accepts status: Open|Closed, acceptingEvidence, inclusive openedFrom / openedTo dates, and sortOrder: DateOpenedNewest|DateOpenedOldest|PublicationDateAscending|PublicationDateDescending. acceptingEvidence: true restricts to accepting businesses; false is unrestricted. All business types remain labelled by isInquiry
  • publications accepts repeated publicationTypeIds, inclusive publishedFrom / publishedTo dates, and sortOrder: PublicationDateAscending|PublicationDateDescending|ResponseDateAscending|ResponseDateDescending. Omitted filters preserve source defaults
  • evidence requires businessId and evidenceType: written|oral; evidence_detail requires evidenceId and the same evidenceType. These IDs occupy separate written/oral namespaces. Records retain typed entities and sourcePath relationships, witnesses, organisations, dates, source state, and supplied document links. Publications remain separate reports, responses, and correspondence; no mode downloads or extracts documents

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
  • Hansard coverage is source-specific: the archive starts on 22 November 1803, the Spoken API minimum date is unknown, and there is no automatic historical-archive fallback

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 actually emitted records, with total only when known; every response stays under 24,000 bytes across both output surfaces
  • Lossless large records — delivery: "full" | "outline" | "fragment"; an oversized record returns contentPage descriptors, and repeating the original inputs plus each contentCursor reconstructs it exactly
  • Compact JSON — content renders complete values as reversible JSON blocks with clickable source links. An outline entry's optional jsonValue is complete JSON text you can decode directly; its contentCursor still retrieves the same value. Fragment sizes adapt to the response budget; concatenate their JSON text before decoding
  • 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
  • Selector errors name each missing or incompatible field and its repair in deterministic order, before network requests; existing error reasons and recovery hints remain stable

Getting started

Connect to the hosted instance, no install:

sh
claude mcp add --transport http uk-parliament-mcp-server https://uk-parliament.caseyjhand.com/mcp

Or run it locally:

sh
claude mcp add uk-parliament-mcp-server -- npx -y @cyanheads/uk-parliament-mcp-server

For other clients, add this to the MCP config file:

json
{  "mcpServers": {    "uk-parliament-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/uk-parliament-mcp-server"]    }  }}

No API key is required. For Docker or a source build, see Running the server.

Configuration

VariableDescriptionDefault
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTInitial HTTP server port; startup logs report the bound port after collision retries.3010
MCP_HTTP_HOSTHTTP bind address.127.0.0.1
MCP_HTTP_ENDPOINT_PATHHTTP MCP endpoint./mcp
MCP_SESSION_MODEHTTP session mode: stateless, stateful, or auto.stateless
MCP_AUTH_MODEAuthentication: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).info
LOGS_DIRDirectory for log files (Node.js only).<app-root>/logs
STORAGE_PROVIDER_TYPEStorage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.in-memory
OTEL_ENABLEDEnable OpenTelemetry.false

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

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+) and internet access to the official Parliament APIs.

  • Clone and install:

    sh
    git clone https://github.com/cyanheads/uk-parliament-mcp-server.gitcd uk-parliament-mcp-server && bun installcp .env.example .env# edit .env for transport, logging, or authentication overrides as needed

  • Build and run the production version:

    sh
    # One-time buildbun run rebuild
# Run the built serverbun run start:http# orbun run start:stdio

  • Run checks and tests:

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

Docker

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/uk-parliament-mcp-server:latest

The image defaults to HTTP transport, stateless sessions, and logs to /var/log/uk-parliament-mcp-server. For an MCP client using stdio, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/uk-parliament-mcp-server:latest"]. Build locally with docker build -t uk-parliament-mcp-server .; --build-arg OTEL_ENABLED=false omits the optional OpenTelemetry peers.

Project structure

DirectoryPurpose
src/mcp-server/tools/definitionsNine tool definitions (*.tool.ts).
src/services/parliament-httpFixed-origin transport, provenance, cursors, and lossless content delivery.
src/services/billsBill search, scrutiny records, publications, and reference directories.
src/services/membersMember discovery, profiles, biographies, interests, and voting history.
src/services/divisionsCommons/Lords division metadata and recorded voter collections.
src/services/hansardSpoken contribution search and historical coverage metadata.
src/services/questionsWritten question previews and complete question/answer records.
src/services/committeesCommittee business, memberships, publications, evidence 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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE 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.

Source: README.md at commit 225ba11

Tools

9

ukparl_lookup_reference

Ukparl Lookup Reference

Resolve Parliament filter IDs and inspect source coverage before searching. Use identifiers for ID namespaces and required selectors, coverage for Hansard date limitations, or a named reference topic for filter IDs. Follow opaque collection cursors with the same filters; use contentCursor to reconstruct an oversized selected payload.

ParametershouselimittopicrequiredcursornameContainscontentCursor

ukparl_search_bills

Ukparl Search Bills

Search Westminster bill summaries by title, current or originating House, session, sponsoring member, department, reference stage, bill type or status, with optional official ordering. Use ukparl_lookup_reference for stage/type/department IDs and ukparl_get_bill for complete selected records. Department IDs are distinct from answering-body IDs. inAmendableStage=true restricts to amendable stages; false is unrestricted. No session or date scope is inferred. Follow collection cursors with the same filters; use contentCursor to reconstruct an oversized item.

ParametershouselimitquerycursormemberIdstageIdssessionIdsortOrderisDefeatedbillTypeIdsisWithdrawndepartmentId+3 more

ukparl_get_bill

Ukparl Get Bill

Retrieve a Westminster bill overview or select stages, stage, publications, amendments, amendment, motions or motion. Stage/amendment/motion selections require the bill-specific billStageId from section=stages; singular amendment/motion also require itemId from their parent collection. Use amendmentId for amendment retrieval and motion.id for motions. Filter only the amendments collection by amendmentNumber, decision or sponsoring memberId. Collection selectors paginate whole records. Overview leaves publications unchecked; select publications to discover actual supplied legislation.gov.uk statute links. Follow contentCursor with the original selection to reconstruct oversized records.

ParameterslimitbillIdrequiredcursoritemIdsectiondecisionmemberIdbillStageIdcontentCursoramendmentNumber

ukparl_search_members

Ukparl Search Members

Find MPs and peers by name, location or constituency, party, House, and current or historical membership. currentOnly=false includes current and former members. asOf selects historical membership and accepts name only, without House, party or location filters. Search results preserve latest profile fields; retrieve sections with ukparl_get_member. Follow opaque cursors with unchanged filters and use contentCursor for oversized records.

ParametersasOfnamehouselimitcursorpartyIdcurrentOnlyconstituencycontentCursor

ukparl_get_member

Ukparl Get Member

Retrieve a member profile, roles, committee seats, official contact information, registered interests or recorded voting history. Roles without category lists available biography categories; select category to page whole periods. Interests and voting require an explicit House. Committee person IDs differ from member IDs. Voting uses native 20-row pages and reports recorded lobby and teller facts, without lifetime participation metrics. Follow collection cursors with unchanged selectors; use contentCursor to reconstruct oversized records.

ParametershouselimitcursorsectioncategorymemberIdrequiredcontentCursor

ukparl_search_divisions

Ukparl Search Divisions

Search official Commons or Lords division summaries, or use detail, voters or party_totals with a divisionId from the same House. Search supports title/number text, member and inclusive division dates; member searches include memberVote with the recorded House-native lobby and teller flag. Detail preserves complete metadata and teller identities, with roster selectors for voters mode. Voters can filter exact source party labels and House-compatible lobbies. not_recorded means only the source list, never abstention. Party totals count listed non-tellers and tellers separately from official headline counts. Follow collection cursors with unchanged filters; reconstruct oversized content using contentCursor.

ParametersmodehouserequiredlimitlobbypartyquerycursorendDatememberIdstartDatedivisionIdcontentCursor

ukparl_search_hansard

Search spoken Hansard

Search spoken Westminster Hansard contributions by topic, member, House, date or numeric debateSectionId. Returns full source contribution text where supplied, including HTML; previews are labelled summaries. Repeat with a returned debateSectionId to search that section, which does not establish an entire debate transcript. Historical completeness is not guaranteed, including the 2004–2006 website warning despite some API records. Use ukparl_lookup_reference topic=coverage for archive guidance. Follow collection cursors unchanged and contentCursor for lossless oversized contributions; retry timeouts with shorter date windows.

ParametershouselimitquerycursorendDatememberIdstartDatecontentCursordebateSectionId

ukparl_search_questions

Search written questions

Search Westminster written questions and answer previews by text, exact UIN, asking or answering member, House, answering body, answer state and dates. An undated UIN returns candidates across sessions; narrow with tabling dates and retrieve mode=detail with a returned questionId for complete question and answer HTML, corrections and attachment links. A UIN is not a questionId and never determines House. Search includes all sessions and withdrawn questions. Follow collection cursors unchanged; use contentCursor for lossless oversized answers.

ParametersuinmodehouselimitquerycursoransweredmemberIdtabledToansweredToquestionIdtabledFrom+4 more

ukparl_get_committee

Get committees and evidence

Find Westminster committees with mode=search, then use committeeId for detail, members, inquiries or publications. Inquiries returns every committee business type, labelled by isInquiry; use businessId with mode=inquiry for complete business detail or to filter publications. Use publicationId with mode=publication for complete report/publication metadata and source links. Use mode=evidence with businessId and evidenceType=written|oral to list evidence; mode=evidence_detail requires evidenceId and evidenceType in the same namespace. Memberships retain all role periods; personId is distinct from Members API memberId. No document downloads or text extraction. Follow cursors with unchanged filters; contentCursor retrieves oversized records losslessly. Typed entities retain sourcePath relationships to reconstruct nested source metadata.

ParametersmodehouselimitquerycursorstatusopenedTosortOrderbusinessIdevidenceIdmembershipopenedFrom+8 more

Version history

2
  1. v0.1.2LatestOct 26, 2026
  2. v0.1.1Oct 25, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts