companies-house-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@companies-house-mcp search Companies House for Tesco and show me its profile and officers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
companies-house-mcp
An MCP server that lets Claude look up UK companies: search by name, then pull a company's profile, officers or filing history by number. It talks to the Companies House Public Data API over stdio.
I built it because the interesting problem is not the HTTP. The API is public
and the calls are trivial. The problem is the contract: deciding what the
model should be able to ask for, what comes back, and how it learns that
something went wrong. That is where almost all of the thinking went, and it is
what the rest of this file is about. If you want the reasoning in full, with
the options I turned down, it is in DECISIONS.md.
Setup
You need a free API key. Register an application at https://developer.company-information.service.gov.uk/, create a key for the "Public Data API", and copy it.
Then:
npm install
npm run buildPoint Claude Desktop at the built server by adding this to its config file
(%APPDATA%\Claude\claude_desktop_config.json on Windows,
~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"companies-house": {
"command": "node",
"args": ["C:\\path\\to\\companies-house-mcp\\dist\\index.js"],
"env": { "COMPANIES_HOUSE_API_KEY": "your-key-here" }
}
}
}The key is read from the environment and nowhere else. If it is missing the server refuses to start and says why, rather than failing on the first call. Restart Claude Desktop and the four tools appear.
Related MCP server: companies-house-mcp
What each tool returns
This is copied from an actual run against the live API. The >>> and <<<
layout is a tidied rendering of the MCP client's output, reformatted for
readability; the request arguments and the response bodies are untouched. The
requests are the lines beginning >>>, the responses follow.
>>> company_search {"query":"tesco","items_per_page":2}
<<<
{
"query": "tesco",
"total_results": 356,
"items_per_page": 2,
"start_index": 0,
"items": [
{
"company_number": "00445790",
"title": "TESCO PLC",
"company_status": "active",
"company_type": "plc",
"date_of_creation": "1947-11-27",
"address_snippet": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA"
},
{
"company_number": "09384423",
"title": "KFORD TYRES (GORNAL) LTD",
"company_status": "active",
"company_type": "ltd",
"date_of_creation": "2015-01-12",
"address_snippet": "2 Dawley Brook Road, Kingswinford, England, DY6 7BD"
}
]
}
>>> company_profile {"company_number":"00445790"}
<<<
{
"company_number": "00445790",
"company_name": "TESCO PLC",
"company_status": "active",
"company_type": "plc",
"data_note": "This profile is a fixed projection. Only the fields present here are fetched. If a property you need (for example charges or insolvency history) is not present, it was not retrieved, not necessarily false.",
"date_of_creation": "1947-11-27",
"jurisdiction": "england-wales",
"registered_office_address": {
"address_line_1": "Tesco House, Shire Park",
"address_line_2": "Kestrel Way",
"locality": "Welwyn Garden City",
"postal_code": "AL7 1GA",
"country": "United Kingdom"
},
"sic_codes": ["47110"],
"accounts": {
"next_due": "2027-08-26",
"next_made_up_to": "2027-02-26",
"overdue": false
}
}
>>> company_officers {"company_number":"00445790","items_per_page":2}
<<<
{
"company_number": "00445790",
"active_count": 11,
"resigned_count": 63,
"total_results": 74,
"items_per_page": 2,
"start_index": 0,
"items": [
{ "name": "TAYLOR, Christopher Jon", "officer_role": "secretary", "appointed_on": "2025-04-14" },
{
"name": "BETHELL, Melissa",
"officer_role": "director",
"appointed_on": "2018-09-24",
"nationality": "British",
"country_of_residence": "United Kingdom",
"date_of_birth": { "month": 9, "year": 1974 }
}
]
}
>>> company_filing_history {"company_number":"00445790","items_per_page":2}
<<<
{
"company_number": "00445790",
"total_count": 8372,
"items_per_page": 2,
"start_index": 0,
"items": [
{
"transaction_id": "MzU0MzY3ODg5MGFkaXF6a2N4",
"category": "capital",
"date": "2026-09-16",
"type": "SH03",
"description": "Return of purchase of own shares",
"description_code": "capital-return-purchase-own-shares",
"pages": 4,
"paper_filed": true
},
{
"transaction_id": "MzUzOTMzNzQ1OWFkaXF6a2N4",
"category": "capital",
"date": "2026-08-26",
"type": "SH06",
"description": "Cancellation of shares",
"description_code": "capital-cancellation-shares",
"pages": 4,
"paper_filed": true
}
]
}
>>> company_profile {"company_number":"not-a-number"}
<<< [isError]
{ "ok": false, "error": { "code": "INVALID_COMPANY_NUMBER", "message": "\"not-a-number\" is not a valid company number. Expected eight characters: digits, or a two-letter prefix then six digits, for example 00000006 or SC123456." } }
>>> company_profile {"company_number":"99999999"}
<<< [isError]
{ "ok": false, "error": { "code": "COMPANY_NOT_FOUND", "message": "No company exists for that number." } }A few things in that run are the whole point. The search carries
company_status, company_type, date_of_creation and an address on every
hit, so the model can pick Tesco PLC over a tyre fitter in Kingswinford
without a second call. The two error cases come back as ordinary results the
model can read, flagged isError, each with a code it can branch on. And
the invalid number never reached the API: it was rejected locally.
The figures are whatever the register held the day I ran this: 356 companies match "tesco", Tesco PLC has 8,372 filings and 74 officer appointments on record, and its accounts are next due on 26 August 2027.
Claude choosing the tools itself
The block above proves the server responds. This proves the contract works. I
wired the four tools into Claude with nothing else connected and asked a plain
question. The exchange below is from a headless claude run with the server
attached; I reformatted it, cut the CLI's own internal bookkeeping, and
shortened the final answer, but the tool calls and the order Claude made them
in are exactly as they happened.
Me: Who runs Tesco and when are their next accounts due?
Claude: I'll search Companies House for Tesco, then pull the officers and
profile for the right entity.
company_search {"query":"Tesco PLC","items_per_page":10}
company_profile {"company_number":"00445790"}
company_officers {"company_number":"00445790","items_per_page":50}
Claude: Tesco PLC (00445790) is active, registered at Tesco House, Welwyn
Garden City. Its next accounts are due 26 August 2027, made up to
26 February 2027, not overdue. The register lists 11 active officers,
among them Ken Murphy (director, appointed 1 October 2020) and
Christopher Taylor (secretary, appointed 14 April 2025), and 63
resigned.Claude was never given the company number. It searched, read company_status
and company_type off the search result to settle on 00445790 out of 356
matches, and chained into profile and officers without being told to. That is
the search-carries-enough-to-decide design doing the job it exists for.
The contract, and why it looks like this
Four tools, not one tool with a mode. A single tool would have to mark every
argument optional, because company_number is required for three of the four
jobs and meaningless for search. Four tools give the model four tight schemas,
so a call with a missing argument fails against the schema it was handed rather
than three steps later at the API. I rejected the mode parameter for that
reason.
Trimmed responses, not raw upstream JSON. A company profile from Companies
House has more than thirty top-level fields. Most of them the model will never
read, and they cost tokens on every call. I project down to a narrow set and,
while I am there, fix an upstream inconsistency: the profile calls the company
type type, search calls it company_type, and I expose one name. The cost is
fidelity. If you want has_charges, this does not give it to you. I think that
is the right trade for a model client, but it is a trade, and it creates one
specific hazard.
The hazard is that the model cannot tell "absent because it is false" from
"absent because I trimmed it". So the boundary is visible on purpose: each
tool description lists the fields it returns, and the profile carries a
data_note saying as much. I rejected an include_fields parameter, which
would have let the model pull extras but would also have reopened the gap
between the schema and the projection that sealing the contract is meant to
close.
Errors split in two. Not-found, invalid-number, rate-limited and upstream-unavailable come back as readable results, because the model can act differently on each. A missing or bad key does not: that is an operator problem, so the server validates the key at startup and refuses to run without one. A 401 arriving mid-session, after a key that worked, is its own code so the model reports it instead of retrying.
Paging is capped at 100 per call. Companies House documents no maximum, which surprised me, so the cap is mine and the code says so. Uncapped, a model could ask for ten thousand filings and spend the whole rate limit on one question.
That rate limit, 600 requests per five minutes per key, is handled before the
fact, not discovered by being refused. A sliding-window limiter holds requests
under the line and waits for a slot; if the wait would be too long it returns
RATE_LIMITED with a seconds-to-wait rather than blocking forever. I would
rather the server know the limit than learn it from a 429.
What it does not do
It covers four endpoints. No charges, no persons-with-significant-control, no document downloads, no insolvency detail. I scoped it to the things a person actually asks about a company and stopped.
The filing description table is the weak point. Companies House returns filing descriptions as enum keys, readable only through a reference file it publishes separately. I bundled a hand-copied subset of that file, so an unseen code falls back to a prettified version of the key. It works, and the original code is always returned alongside, but a hand-copied table goes stale silently. With more time I would pull the full enumeration file at build time instead of maintaining a slice of it by hand.
Two other things I would change. The cache is per-process and in-memory with a TTL but no size bound, which is fine for a desktop tool serving one person and wrong for anything larger. And the rate limiter is per-process too, so two servers sharing one key could still exceed the limit between them; a shared limiter would fix it and is not worth the complexity here.
Tests
npm testThe suite runs against fixtures captured from real responses and never touches
the network. The fixtures were taken from companies 00000006 (dissolved) and
00445790 (active) so both the cessation path and the upcoming-accounts path are
covered by real data. npm run test:live adds three tests that hit the real
API, and is skipped unless you set a key. npm run capture regenerates the
fixtures from live responses.
Licence
MIT. See LICENSE.
Available Tools
4 toolscompany_filing_historyUK company filing historyA
List the filing history of one UK company by its number. Returns items each with transaction_id, category, date, type, a resolved description, the original description_code, pages and paper_filed. Filter with the category parameter. Paged. On failure returns an error object with a code field.
Inputs: company_number (required), category, start_index, items_per_page.
company_officersUK company officersA
List the officers of one UK company by its number. Returns active_count and resigned_count, then items each with name, officer_role, appointed_on, resigned_on, nationality, occupation, country_of_residence and date_of_birth (month and year only). Paged. On failure returns an error object with a code field.
Inputs: company_number (required), order_by, start_index, items_per_page.
company_profileUK company profileA
Get the profile of one UK company by its number. Returns company_name, company_number, company_status, company_type, date_of_creation, date_of_cessation, jurisdiction, registered_office_address, sic_codes and accounts due dates. This is a fixed subset; a property not listed was not fetched, so do not read its absence as false. On failure returns an error object with a code field, including COMPANY_NOT_FOUND and INVALID_COMPANY_NUMBER.
Inputs: company_number (required).
company_searchSearch UK companiesA
Search UK companies by name. Returns a list of matches, each with company_number, title, company_status, company_type, date_of_creation and address_snippet: enough to choose the right company without a follow-up call. Use the returned company_number with the other tools. On failure returns an error object with a code field.
Inputs: query (required), start_index, items_per_page.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct operation: name search, single-company profile, officer listing, and filing history. The search tool explicitly tells the agent to use the returned company_number with the other three, and the resource/action boundaries are unambiguous.
All four tools follow a consistent snake_case pattern with a shared 'company_' prefix and a clear resource noun (search, profile, officers, filing_history). No style mixing or vague verbs.
Four tools is a tight, well-scoped surface for a read-only Companies House lookup server. Each tool covers a core operation and there are no redundant or filler tools.
The surface covers the most common lookups (search, profile, officers, filings) but omits notable Companies House resources such as charges, persons with significant control, and insolvency data. Agents needing those will hit dead ends, though core workflows are supported.
Related MCP Connectors
UK Companies House company search, officers and PSC via the official API. Runs on Apify.
CompanyLens is a remote MCP server giving AI agents instant access to official company registry data across 19 jurisdictions in Europe, the Americas, and Asia-Pacific. Eighteen read-only tools let you search companies and people, look up officers and beneficial owners, map corporate networks through shared directors, screen names against the UK disqualified directors register, find every company at a registered address, and pull filing history — all from a single connector. Visit our website: https://companylens.io
Companies House MCP — UK statutory company registry (BYO key)
Dated UK company facts from public records, with a signed credential check. Free tools need no key.
71
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables looking up UK companies, officers, ownership, filings, and running due diligence checks via the Companies House API, usable from AI tools like Claude or Cursor.12 npm39MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to search and retrieve UK Companies House data including company profiles, officers, and filing history via the official API.4199 npm1MIT
- FlicenseBqualityDmaintenanceProvides access to UK Companies House public data, enabling search and retrieval of company profiles, officers, filing history, and more through natural language queries.12-
- AlicenseNot gradedqualityDmaintenanceEnables querying UK company data including search, profiles, officers, filings, and persons with significant control via Companies House API.MIT