companies-house-mcp

Production-grade Model Context Protocol server for the UK Companies House API.

Point any MCP-aware assistant (Claude Desktop, Claude Code, Cursor, custom agents) at UK company data. Auth, rate limiting, in-memory caching, structured errors, and a real test suite included — not a tutorial demo.

Status: alpha (v0.1). Five core tools shipped. Free filing-history documents, resumable-filings, and disqualified-officers lookups on the roadmap.

Why this exists

The official MCP reference servers are explicitly educational. They ship without auth, rate limiting, caching, or tests — deliberately, so learners can read them in an afternoon. Every serious team building on MCP ends up re-implementing the same production concerns from scratch.

This is one of them, done properly, against a UK data source that accountants, KYC/AML teams, sales-ops, and journalists genuinely use every day.

Tools exposed

Every tool returns structured JSON — the client model doesn't have to parse HTML or free-form text.

Install & configure

Requires Node.js 20+ and a free Companies House API key from developer.company-information.service.gov.uk.

Claude Desktop

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "companies-house": {
      "command": "npx",
      "args": ["-y", "companies-house-mcp"],
      "env": {
        "CH_API_KEY": "your-key-here"
      }
    }
  }
}

Restart Claude Desktop. Ask it: "Look up MORRIS AI LTD on Companies House and tell me who the directors are."

Claude Code

claude mcp add companies-house npx -y companies-house-mcp -- --env CH_API_KEY=your-key-here

Local dev

git clone https://github.com/shadowborn-dev/companies-house-mcp
cd companies-house-mcp
npm install
cp .env.example .env    # add your API key
npm run build
npm start

Docker

docker build -t companies-house-mcp .
docker run --rm -i -e CH_API_KEY=your-key-here companies-house-mcp

Try it in the browser (MCP Inspector)

The fastest way to poke at the tools without wiring the server into Claude Desktop is the official MCP Inspector — a web UI that connects to any MCP server and lets you call its tools with a form.

# put your key in .env first (or export CH_API_KEY=... in the shell)
npm run inspect

That builds the server, launches the Inspector in a local browser tab, and connects to the built server over stdio. You'll see the five tools listed on the left; click one, fill in the form on the right (company_number: "12345678" for get_company_profile, or query: "morris" for search_companies), hit Run tool, and the raw JSON response comes back below. Handy for verifying a tool works before you plug the server into Claude.

Production concerns handled

Auth. Companies House uses HTTP Basic with the API key as the username. This server wraps that transparently — you only ever set CH_API_KEY.

Rate limiting. Companies House enforces 600 requests per 5-minute rolling window per API key. This server ships a token-bucket limiter tuned to match — requests over the budget queue and wait rather than being sent through and 429'd back. Configurable via CH_RATE_LIMIT_MAX and CH_RATE_LIMIT_WINDOW_SECONDS.

Caching. In-memory LRU with per-entry TTL (default 5 minutes). Company profiles rarely change intraday, so a cache dramatically cuts request count for repeated lookups. Configurable via CH_CACHE_TTL_SECONDS and CH_CACHE_MAX_ENTRIES.

Structured errors. Every failure surfaces as a typed error class the model can reason about — NotFoundError, UnauthorizedError, RateLimitedError, UpstreamError — instead of a generic 500.

Tests. Vitest covers the rate limiter, cache eviction, and the HTTP client with mocked fetch. npm test runs the whole suite.

Configuration reference

Roadmap

• v0.2 — get_filing_document (fetches the PDF or iXBRL underlying a filing).

• v0.3 — disqualified_officers search + officer_appointments (all companies a person is an officer of).

• v0.4 — Streamable HTTP transport for remote/hosted deployments.

• v0.5 — Optional Redis-backed cache + rate limiter for multi-instance deployments.

Honest caveats

• The Companies House API returns data as filed — occasionally with typos, inconsistent capitalisation, or delays of days between filing and appearing. This server does not clean or reconcile any of that.

• Rate-limit budgeting is per-API-key. If you share a key across multiple instances of this server, they will not coordinate — colocate to one instance or supply a distributed limiter in v0.5.

• Not affiliated with or endorsed by Companies House.

License

MIT. See LICENSE.