companies-house-mcp
Production-grade MCP server for UK Companies House. Auth, rate limits, tests — not a toy.
§ 01 · Overview
A Model Context Protocol server exposing the UK Companies House API to MCP-compatible clients (Claude Desktop, Claude Code, custom agents). Ships with transparent HTTP Basic authentication, a sliding-window rate limiter tuned to the Companies House 600-req/5min ceiling, in-memory LRU caching with per-entry TTL, typed error classes surfaced to the calling model, and a Vitest suite. The underlying HTTP client is also published as a library entrypoint for direct use in Node projects that don't need the MCP server layer.
§ 02 · Estimated impact
§ 03 · Architecture
- 01
Configure the server in a Claude Desktop or Claude Code MCP config with a single `CH_API_KEY` environment variable. The server auto-builds on install when consumed as a git dependency.
- 02
Exposes five typed MCP tools: search_companies, get_company_profile, list_officers, list_filings, and get_psc (persons with significant control). Every tool has a zod input schema and a documented purpose so the calling model can reason about which tool to invoke.
- 03
The sliding-window rate limiter matches the Companies House 600-req/5min per-key ceiling. When the window saturates, subsequent requests are queued and back-pressured, so an eager model does not receive spurious 429s. Typed error classes (NotFoundError, UnauthorizedError, RateLimitedError, UpstreamError) are surfaced to the model as structured tool errors.
- 04
Ships with a multi-stage Dockerfile, GitHub Actions CI on Node 20 and 22, and a library entrypoint (`companies-house-mcp/client`) that other Node projects can import to reuse the client without running the server.
Stack
§ 04 · Positioning
The official MCP reference servers are educational examples — they intentionally omit authentication, rate limiting, caching, and tests so that the protocol is readable in an afternoon. Building a production deployment on top of a reference server therefore requires re-implementing all of those concerns. This server addresses that gap for a UK data source that regulated professions consult daily.
| Alternative | Trade-off |
|---|---|
| The official MCP reference servers | Effective as protocol tutorials. Not suitable for production deployment without additional work on authentication, rate limiting, caching, and observability. This server ships those production concerns as built-ins. |
| Direct Companies House API integration per project | The same integration is typically rebuilt in each downstream project, consuming engineering effort per client. This server allows the same integration to serve every MCP-capable client identically. |
| Screen-scraping the Companies House website from an assistant | Fragile against layout changes, lacks rate-limit awareness, and produces unstructured output. Structured MCP tool calls are more reliable and lower-latency than scraping. |
§ 05 · Frequently asked
How does companies-house-mcp handle the 600 requests per 5-minute rate limit?
The server ships a sliding-window rate limiter tuned to that exact ceiling. Requests that would exceed the window are queued and back-pressure the calling agent rather than being sent through and receiving a 429. Configurable via the CH_RATE_LIMIT_MAX and CH_RATE_LIMIT_WINDOW_SECONDS environment variables.
Can I use the underlying Companies House client without running the MCP server?
Yes. The HTTP client is exported at the /client subpath. Import CompaniesHouseClient from @antonmorris/companies-house-mcp/client in any Node project and get the same authentication, rate limiting, caching, and typed error classes — with no MCP server process running.
What data does companies-house-mcp cache and for how long?
Successful Companies House responses are cached in an LRU + TTL in-memory store, defaulting to 5-minute TTL and 1,000 entries. The cache is per-process, so a server restart clears it. Configure with CH_CACHE_TTL_SECONDS and CH_CACHE_MAX_ENTRIES.