firmfind

firmfind

在官方商业登记册中查找公司，然后获取目标公司的完整记录。firmfind 是 CompanyData 服务的轻量客户端：可按名称、地点、行业代码、公司规模、成立年限，以及记录是否包含电子邮件地址、电话号码、网站或具名 CEO 搜索登记信息；按 ID 导出单家公司的完整条目；也可将模糊记得的地名解析为城市建议，再用它进行搜索。

服务返回的内容会原样返回——整个过程中不会进行删减、重命名或摘要。

配置

• COMPANYDATA_API_KEY（必需）——每次请求都会通过 x-api-key 标头发送。未设置时，所有工具都会报错 COMPANYDATA_API_KEY is not set，且不会发出请求。
• COMPANYDATA_API_BASE_URL（可选）——API 基础 URL。默认为 https://app.companydata.com。

工具

• company_search — 按名称、地点、行业、规模和联系信息筛选条件搜索公司。38 个参数均为可选：分页（page、pageSize）、身份标识和文本筛选条件（ID、search、sic4Digits、importExportCode、legalStatus、statusCode、subsidiaryCode、countryCode、provinceName、cityName、streetName、regionName、countryName、postalCode、phoneNumber、email、worldwideHeadquarterID、nationalId、website）、数值范围（postalCodeIntegerMin/Max、employeesHereMin/Max、employeesTotalMin/Max、annualSalesMin/Max、foundingYearsMin/Max）和存在性标志（hasEmail、hasMarketability、hasPhone、hasWebsite、hasNationalID、hasCEOName、strictCountry）。只会发送实际设置的参数；布尔值会以 true/false 的形式发送，范围边界使用 API 带方括号的传输名称，例如 employeesHere[min]。
• company_enrich — 按 CompanyData ID（必需）导出一家公司的完整记录。此调用始终会向导出端点请求记录的导出格式。
• field_lookup — 根据地点名称 search（必需）获取城市建议，可选用 countries 缩小范围，并用 limit 限制结果数量。

上游返回非 2xx 响应时会报错 companydata error: HTTP <status>；API 无法访问时会报错 companydata unreachable。

端点来源

工具接口、密钥环境变量和标头、默认基础 URL 及补全行为由原始软件包的 README 确定；参数名称、类型和传输名称由官方 OpenAPI 文档确定：

• 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

每个工具都是一个子命令，接受一个 JSON 参数字符串：

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

输出为工具的结果文本（成功时为上游响应正文）。退出代码：成功时为 0，运行时错误（包括缺少密钥或上游故障）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/firmfind mcp

MCP 客户端配置：

{
  "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"}'

开发

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

许可证

MIT — 版权所有 (c) 2026 Rene Turcios