io.github.qinisolabs/companieswise

companieswise

Verified UK company lookup & number validation for AI agents — official Companies House data, not guesses.

Verified, trustworthy data tools for AI agents. "Qiniso" means "truth" in Zulu.

Website · npm · MCP Registry

Ask an LLM "what's the registered name and status of company 00445790?" and it will answer confidently — and usually wrongly: invented names, the wrong status, a fabricated incorporation date. Company records live in the Companies House register, not a model's weights. companieswise looks the number up in the official Companies House snapshot and returns the real registered details — or an honest "not found" instead of a guess.

⚠️ Read this first — what the data is

• UK-wide (England & Wales, Scotland, Northern Ireland).
• A monthly snapshot of the live register. Company status is as of the dataset date, not real-time — a company dissolved last week may still read "Active" until the next snapshot, and dissolved companies are generally absent. For current status, check the live register.
• Not advice. Not legal, financial, credit, or KYC/AML advice, and not a substitute for statutory due diligence.

Install

{ "mcpServers": { "companieswise": { "command": "npx", "args": ["-y", "companieswise"] } } }

Then load the real data once (the package ships with only a small sample):

npx -p companieswise companieswise-update

This downloads the latest monthly Companies House snapshot (~tens of MB) to a local cache. Re-run it whenever you want to refresh; a GitHub Action rebuilds the snapshot monthly, so companieswise-update always fetches the current month. Until you run it, validate_company_number works fully and lookup_company/search_company clearly say they're on the sample.

Optional: live mode (BYO key)

By default companieswise serves the monthly snapshot (offline, no key). If you set a free Companies House API key, it switches to live queries against the official Companies House API instead — real-time register status, including dissolved companies, on your own key (no shared rate limit):

{
  "mcpServers": {
    "companieswise": {
      "command": "npx",
      "args": ["-y", "companieswise"],
      "env": { "COMPANIESWISE_CH_API_KEY": "your-companies-house-api-key" }
    }
  }
}

lookup_company and search_company use the live API when the key is set (results tagged "dataset": "live") and fall back to the snapshot when it isn't ("dataset": "snapshot"), so it's always clear which you're getting. validate_company_number is offline either way. The key is sent only to the official Companies House API. CH_API_KEY is accepted as an alias.

Use it as a library

npm i companieswise

import { lookupCompany, validateCompanyNumber, searchCompany } from "companieswise";

validateCompanyNumber("SC123456");   // { valid: true, prefix: "SC", meaning: "Company registered in Scotland" }
validateCompanyNumber("6").number;   // "00000006" — normalises/zero-pads
lookupCompany("00000006");           // official name, status, type, incorporation date, postcode, SIC — or found:false
searchCompany("greggs");             // companies whose registered name contains your words

A well-formed number that isn't in the snapshot returns found: false with a clear note — it never invents a company.

Tools — 3

Data & monthly auto-refresh

The data is the Companies House Free Company Data Product (UK-wide, live register), published under the Open Government Licence v3.0. Because the real dataset is ~5.6M companies — far too large to bundle into an npm package — the design splits code from data:

• Code ships on npm (tiny).
• Data is built monthly by a GitHub Action (.github/workflows/refresh-data.yml) that downloads the official snapshot, compiles a compact artifact, and publishes it as a GitHub Release asset.
• companieswise-update downloads that artifact into a local cache; every response reports its datasetVersion (the snapshot date).

No API key, no rate limit, no per-request cost — lookups run locally against the cached snapshot. See ARCHITECTURE.md for why, and the hosted/real-time path.

What it is not

• Not real-time. Monthly snapshot of the live register; status is as of the dataset date. For live status use the Companies House API/website.
• Not the full register. The free snapshot is live companies; dissolved companies are generally absent (absent ≠ "never existed").
• Not advice, and not a statutory KYC/AML check.
• Not a guesser — unknown numbers return an honest "not found".

Privacy

This tool runs locally on your machine and is built not to collect, store, or transmit your data — no analytics, no telemetry, no account. By default it uses bundled/cached data offline; only if you set a Companies House API key does it send your lookup and key directly to the official Companies House API (never to Qiniso). Full policy: https://qinisolabs.github.io/privacy.html.

License

Apache-2.0. Company data © Crown copyright, Companies House, Open Government Licence v3.0; see NOTICE.