bartram-companies-house 0.1.0

UK Companies House data via MCP — company search, profiles, officers, beneficial owners, and filings with cleaning and deduplication.

UK Companies House MCP Server

Clean, structured UK company data for AI agents — via the Model Context Protocol.

What this does

This MCP server gives agents access to UK Companies House data — company search, profiles, officer records, beneficial ownership, and filing history — with data cleaning that the raw API doesn't provide.

Companies House data has known quality issues: officer names appear in multiple formats creating ~614K duplicate records, corporate entities get filed as natural persons in PSC (beneficial ownership) data, and addresses arrive in inconsistent formats. This server fixes those problems before the data reaches your agent.

What the cleaning layer does:

• Officer deduplication — fuzzy name matching merges records like "SMITH, John David" and "John Smith" when they share the same role and company.
• PSC entity classification — flags corporate entities incorrectly filed as natural persons, using identification fields and name pattern detection.
• Address normalisation — consistent formatting, postcode standardisation, single-line formatted output.
• Filing descriptions — converts Companies House's hyphenated codes (like termination-director-company-with-name-termination-date) into readable text.
• Company number normalisation — agents can send 445790 and the server correctly zero-pads it to 00445790.
• Full officer pagination — fetches all pages automatically, not just the first 50.
• Data quality annotations — every cleaned record carries _cleaning metadata so agents can see what was changed and why.

Quick start

Works out of the box — no API key needed.

# Install
pip install bartram-companies-house

# Run the MCP server
bartram-companies-house

Or with uvx:

uvx bartram-companies-house

For heavy usage or production workloads, register your own Companies House API key and set it as an environment variable:

export COMPANIES_HOUSE_API_KEY="your-key-here"

Configure with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "companies-house": {
      "command": "uvx",
      "args": ["bartram-companies-house"]
    }
  }
}

Tools

Tool	Description
uk_company_search	Search for UK companies by name or number
uk_company_profile	Get company details — address, status, SIC codes, key dates
uk_company_officers	Get officers with name deduplication
uk_company_psc	Get beneficial owners with entity classification
uk_company_filings	Get filing history with readable descriptions

See SCHEMA.md for full parameter and response documentation with examples.

Example

Ask your agent: "Who are the directors of Tesco?"

The agent calls uk_company_search with query: "Tesco", gets the company number, then calls uk_company_officers with that number. The response includes deduplicated officer records with cleaning metadata:

{
  "data": {
    "items": [
      {
        "name": "MURPHY, Ken",
        "officer_role": "director",
        "appointed_on": "2020-10-01",
        "nationality": "Irish",
        "_cleaning": {
          "deduplicated": true,
          "duplicate_count": 2,
          "original_names": ["MURPHY, Kenneth", "MURPHY, Ken"],
          "note": "Merged 2 records with similar names. Showing most recently appointed."
        }
      }
    ],
    "_cleaning": {
      "original_count": 45,
      "deduplicated_count": 38,
      "duplicates_removed": 7
    }
  },
  "metadata": {
    "source": "Companies House",
    "licence": "OGL v3.0",
    "endpoint": "/company/00445790/officers"
  }
}

Every response includes a metadata envelope with source attribution, licence information, and retrieval timestamp.

Data source

All data comes from the Companies House API and is published under the Open Government Licence v3.0. Crown copyright.

Caching

Responses are cached locally in SQLite to reduce API calls and improve latency:

Endpoint	TTL
Company search	1 hour
Company profile	24 hours
Officers	6 hours
PSC	6 hours
Filing history	1 hour

Cache is stored in ~/.bartram/cache.db by default. Set BARTRAM_DATA_DIR to change the location.

Development

git clone https://github.com/RobertAlsop/bartram_foundry.git
cd bartram_foundry
uv sync --all-extras
uv run pytest
uv run ruff check .

Licence

MIT

---

Built by Bartram Foundry — production-grade MCP tools for UK public data.