# companies-house-mcp

A STDIO-based [MCP](https://modelcontextprotocol.io/) server that exposes the
[UK Companies House public data API](https://developer.company-information.service.gov.uk/)
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](https://docs.astral.sh/uv/), already
   configured for this project):

   ```bash
   uv sync
   ```

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

3. **Set the API key** in your environment:

   ```bash
   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:

```bash
uv run companies-house-mcp
```

With the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for
interactive testing:

```bash
uv run mcp dev src/companies_house_mcp/server.py
```

## Registering with Claude Code / Claude Desktop

Claude Code:

```bash
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`):

```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

| Tool | Description |
|---|---|
| `search_companies` | Search for companies by name or company number |
| `search_officers` | Search for officers (directors, secretaries, etc.) by name |
| `get_company_profile` | Full profile of a company (status, SIC codes, incorporation date, etc.) |
| `get_registered_office_address` | A company's registered office address |
| `list_company_officers` | Officers of a company, current and past |
| `list_filing_history` | A company's filing history |
| `get_filing_history_item` | Detail of a single filing history item |
| `list_persons_with_significant_control` | Persons with significant control (PSCs) over a company |
| `list_charges` | Charges (mortgages) registered against a company |
| `get_charge` | Detail of a single charge |
| `get_insolvency` | Insolvency practice information, if any |
| `list_uk_establishments` | UK establishments linked to a company (overseas companies) |

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

```bash
uv run pytest
```