Companies House

A STDIO-based MCP server that exposes the UK Companies House public data API as tools for MCP clients (Claude Desktop, Claude Code, etc.).

Setup

1. Get an API key. Register at https://developer.company-information.service.gov.uk/, create an application, and generate a key of type REST.

2. Install dependencies (using uv, already configured for this project):

   uv sync
   

   (Or with plain pip in a virtualenv: pip install -e .)

3. Set the API key in your environment:

   export COMPANIES_HOUSE_API_KEY=your-key-here
   

   See .env.example for reference — this project does not auto-load .env files; set the variable in your shell or in your MCP client's server config.

Running

Directly over stdio:

uv run companies-house-mcp

With the MCP Inspector for interactive testing:

uv run mcp dev src/companies_house_mcp/server.py

Registering with Claude Code / Claude Desktop

Claude Code:

claude mcp add companies-house \
  -e COMPANIES_HOUSE_API_KEY=your-key-here \
  -- uv --directory /Users/michaelhughes/companies-house-mcp run companies-house-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "companies-house": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/michaelhughes/companies-house-mcp",
        "run",
        "companies-house-mcp"
      ],
      "env": {
        "COMPANIES_HOUSE_API_KEY": "your-companies-house-rest-api-key"
      }
    }
  }
}

Tools

Company numbers may be passed with or without leading zeros (e.g. 123456 is normalized to 00123456); alphanumeric-prefixed numbers (e.g. SC123456) are left as-is (upper-cased). Company numbers, charge IDs, and filing transaction IDs are all validated to contain only letters and digits before being used in a request — anything else (e.g. stray /, .., ?) is rejected with a clear error rather than silently altering the request.

get_insolvency, list_charges, list_persons_with_significant_control, and list_uk_establishments return a clear empty result (e.g. {"cases": [], "message": "No insolvency data for this company"}) rather than an error when a company simply has none of that data — Companies House 404s these endpoints both for "no data" and for a nonexistent company, so this distinction is made by double-checking the company profile before treating a 404 as "empty."

Companies House rate-limits API keys to 600 requests per 5 minutes; a 429 response is surfaced as a clear tool error including the Retry-After value.

Testing

uv run pytest