firmfind

firmfind

Find companies in official business registers, then pull the full record for the one you meant. firmfind is a small client for the CompanyData service: search the registers by name, place, industry code, company size, age and whether a record carries an email address, a phone number, a website or a named CEO; export the complete entry for a single company by its ID; or resolve a half-remembered place name into city suggestions before you search with it.

Whatever the service returns comes back exactly as it was sent — nothing is trimmed, renamed or summarised on the way through.

Configuration

• COMPANYDATA_API_KEY (required) — sent on every request as the x-api-key header. When it is not set, every tool fails with COMPANYDATA_API_KEY is not set and no request is made.
• COMPANYDATA_API_BASE_URL (optional) — API base URL. Defaults to https://app.companydata.com.

Tools

• company_search — search companies by name, location, industry, size and contact filters. All 38 arguments are optional: paging (page, pageSize), identity and text filters (ID, search, sic4Digits, importExportCode, legalStatus, statusCode, subsidiaryCode, countryCode, provinceName, cityName, streetName, regionName, countryName, postalCode, phoneNumber, email, worldwideHeadquarterID, nationalId, website), numeric ranges (postalCodeIntegerMin/Max, employeesHereMin/Max, employeesTotalMin/Max, annualSalesMin/Max, foundingYearsMin/Max) and presence flags (hasEmail, hasMarketability, hasPhone, hasWebsite, hasNationalID, hasCEOName, strictCountry). Only arguments you actually set are sent; booleans go as true/false and the range bounds use the API's bracketed wire names, for example employeesHere[min].
• company_enrich — export the full record for one company by its CompanyData ID (required). The call always asks the export endpoint for the export form of the record.
• field_lookup — city suggestions for a place-name search (required), optionally narrowed by countries and capped by limit.

An upstream non-2xx reply fails with companydata error: HTTP <status> and an unreachable API with companydata unreachable.

Endpoint provenance

The tool surface, the key environment variable and header, the default base URL and the enrichment behaviour are pinned by the original package's README; the parameter names, types and wire names are pinned by the official OpenAPI document:

• GET <base>/api/company/search?<params> — company_search.
• GET <base>/api/company/export?ID=<id>&export=true — company_enrich.
• GET <base>/api/cities?<params> — field_lookup.

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/firmfind company_search '{"search":"bakery","countryCode":"NL","hasEmail":true}'
npx @reneturcios/firmfind company_enrich '{"ID":"abc-123"}'
npx @reneturcios/firmfind field_lookup '{"search":"amster","countries":"NL","limit":5}'
npx @reneturcios/firmfind --version

Output is the tool's result text (the upstream body on success). Exit codes: 0 on success, 1 on a runtime error (including a missing key or an upstream failure), 2 on a usage error.

MCP server

npx -y @reneturcios/firmfind mcp

MCP client config:

{
  "mcpServers": {
    "firmfind": {
      "command": "npx",
      "args": ["-y", "@reneturcios/firmfind", "mcp"],
      "env": {
        "COMPANYDATA_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/firmfind
docker run --rm ghcr.io/cloudcorprecords/firmfind company_search '{"search":"bakery"}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios