1. 项目概述一个连接商业世界的智能数据管道如果你曾经需要查询一家公司的注册信息、董事详情、财务报告或者进行商业尽职调查你大概率听说过或使用过像英国公司注册处这样的官方商业登记机构。这些机构是商业世界的“户口本”存储着海量、权威但往往分散且不易直接调用的结构化数据。aicayzer/companies-house-mcp这个项目正是为了解决这个痛点而生。它是一个基于 Model Context Protocol 的服务器实现其核心使命是将英国公司注册处的公开数据转化为大型语言模型能够轻松理解、查询和利用的结构化上下文。简单来说它扮演了一个“智能翻译官”或“专业数据接线员”的角色。对于开发者、数据分析师、金融从业者或任何需要批量、自动化处理英国公司信息的团队而言这个工具意味着你不再需要手动爬取网站、解析复杂的 JSON 或 PDF 文件或者与原始的 API 直接“搏斗”。你只需要用自然语言向你的 AI 助手例如 Claude Desktop、Cursor 等集成了 MCP 客户端的工具提问比如“帮我查一下 Acme Corp Ltd 的最新年度账目摘要”或“列出所有在伦敦注册的、从事可再生能源业务的活跃公司”这个 MCP 服务器就会在背后默默工作调用 Companies House 的官方 API获取数据并以清晰、标准化的格式返回给 AI再由 AI 组织成你想要的答案或报告。这个项目的价值在于它极大地降低了商业数据获取和利用的技术门槛将原本需要编程知识和 API 理解能力的任务变成了人人可用的对话式查询。无论是快速验证商业伙伴资质还是进行市场趋势分析亦或是学术研究它都能提供一个高效、可靠的自动化入口。接下来我将深入拆解这个项目的设计思路、技术实现以及如何让它为你所用。1.1 核心需求与场景解析为什么我们需要一个专门针对 Companies House 的 MCP 服务器这得从原始数据获取的复杂性说起。Companies House 虽然提供了开放的 REST API但其使用并非毫无门槛。首先你需要注册获取 API 密钥并理解其速率限制和认证方式。其次其 API 返回的数据结构嵌套较深字段名专业直接解读需要对照官方文档。例如获取一家公司的“人员”信息可能返回包含董事、秘书等角色的列表每个角色下又有任命日期、国籍、住址等多个子字段。对于非技术背景的业务人员或者希望快速原型验证的开发者这些步骤都是不小的负担。aicayzer/companies-house-mcp精准地瞄准了以下几个核心场景1. 增强AI助手的专业能力这是 MCP 协议的根本目的。通过将此服务器配置到 Claude Desktop 等工具中你的 AI 助手瞬间获得了查询英国公司信息的“超能力”。你可以直接在对话中要求它进行公司背景调查、比较不同公司的财务状况或者追踪某位董事在不同公司的任职网络。AI 利用此工具获取到精确数据后可以进一步进行总结、分析或整合到更广泛的报告中。2. 自动化商业情报与尽职调查对于投资机构、律所、咨询公司或大型企业的战略部门定期监控一批目标公司的状态变更如董事变更、注册地址迁移、提交财务报告是常规工作。传统方式是人工定期抽查或购买昂贵的商业数据库。通过将此 MCP 服务器与自动化脚本或工作流例如结合 n8n, Zapier 或简单的 cron job 调用 MCP 客户端结合可以低成本地构建一个实时监控告警系统。3. 数据清洗与集成管道如果你需要将 Companies House 的数据与你内部的 CRM、ERP 系统或其他数据库进行整合这个项目可以作为一个标准化的数据抽取层。它统一了数据访问接口输出结构化的 JSON 数据方便后续的数据清洗、转换和加载流程。4. 教育与研究学术研究者或学生可以利用此工具便捷地获取大量公司样本数据用于研究公司治理、区域经济活力、行业分布等课题而无需编写复杂的爬虫程序。项目的设计哲学非常明确封装复杂性暴露简单性。它将认证、API 调用、错误处理和初步的数据格式化这些“脏活累活”全部打包在服务器内部最终向 AI 模型提供一个或几个语义清晰、功能明确的“工具”Tools。用户和 AI 都只需要关注“想查什么”而不是“怎么去查”。2. 技术架构与核心组件拆解要理解这个项目如何运作我们需要深入其技术内核。它不是一个简单的脚本而是一个遵循了特定协议的标准化服务器应用。其架构可以清晰地分为三层协议层、业务逻辑层和数据接入层。2.1 Model Context Protocol 协议层这是项目的基石。MCP 是由 Anthropic 提出的一种开放协议旨在为标准化的方式让 AI 应用程序客户端能够安全、可控地访问外部工具、数据源和计算资源服务器。你可以把它想象成 AI 世界的“USB 标准”或“驱动协议”。它定义了客户端与服务器之间通信的“语言”和“规则”。在这个项目中MCP 服务器主要提供两类资源工具这是核心。服务器会向客户端宣告自己具备哪些能力比如search_companies搜索公司、get_company_profile获取公司详情、get_officers获取公司人员列表等。每个工具都有明确的输入参数描述例如搜索需要查询字符串和可选的结果数量。AI 客户端在需要时会调用这些工具。上下文服务器也可以主动提供一些静态或动态的上下文信息帮助 AI 更好地理解领域。例如它可以提供一段关于 Companies House 数据字段的说明文档作为 AI 的背景知识。MCP 通信通常通过标准输入输出或 HTTP 进行传输格式为 JSON-RPC。这意味着这个服务器可以轻松地与任何实现了 MCP 客户端协议的应用程序集成具有很好的通用性。2.2 业务逻辑与工具实现层这一层是项目的大脑负责将 MCP 协议定义的抽象“工具”调用映射到具体的 Companies House API 操作上。我们以最常用的几个工具为例拆解其内部逻辑工具search_companies的实现流程参数验证与格式化接收来自 AI 客户端的参数如q查询词和items_per_page每页结果数。服务器会检查参数有效性并格式化为符合 Companies House API 要求的查询字符串。例如它可能需要处理用户输入的公司名中的特殊字符。API 调用使用配置好的 API 密钥向https://api.company-information.service.gov.uk/search/companies发送 HTTP GET 请求。这里必须妥善处理 HTTP 状态码如 429 表示速率限制需要实现重试机制。响应解析与过滤Companies House API 返回的搜索结果可能包含很多字段。服务器并非原封不动地转发而是会提取最核心、对 AI 和用户最有价值的信息如公司编号、公司名、注册地址、公司状态、公司类型等。它可能还会计算并添加一些衍生字段比如将注册日期转换为更易读的格式。标准化输出将过滤和格式化后的数据封装成 MCP 协议规定的工具调用结果格式返回给客户端。输出会被设计得简洁、结构化方便 AI 模型阅读理解。工具get_company_profile的深度处理获取公司详情比搜索更复杂因为返回的数据量更大、结构更深。服务器需要从https://api.company-information.service.gov.uk/company/{company_number}获取数据。智能解析嵌套结构。例如registered_office_address可能是一个包含多行地址、邮编、国家的对象服务器可能需要将其拼接成一个格式良好的字符串。处理可选字段。有些公司可能没有accounts账目或confirmation_statement确认声明信息服务器需要优雅地处理这些缺失情况而不是导致错误。关键信息提取。对于财务数据它可能只提取最近一个会计年度的营业额、利润等关键指标而不是把整个庞大的账目文件都塞给 AI。注意一个优秀的 MCP 服务器实现其业务逻辑的核心在于“信息降噪”和“语义增强”。它不仅要获取数据更要让数据对 AI 更友好。这意味着移除无关的 technical metadata将代码化的枚举值如公司状态 “active”翻译成自然语言“活跃”并将相关的数据点分组呈现。2.3 数据接入与配置层这是项目的“后勤部门”负责所有外部依赖和运行配置。API 密钥管理安全地管理 Companies House 的 API 密钥是重中之重。项目通常会通过环境变量如COMPANIES_HOUSE_API_KEY来读取避免将密钥硬编码在代码中。它还需要处理密钥无效或过期的情况给出明确的错误提示。HTTP 客户端与错误处理需要选择一个稳健的 HTTP 客户端库如 Python 的httpx或requests来处理网络请求。必须实现完善的错误处理包括网络超时、API 限流、响应格式异常等并确保这些错误能通过 MCP 协议清晰地反馈给客户端而不是让服务器静默崩溃。日志与监控为了方便调试和运行状态追踪服务器应集成日志功能记录关键的操作如收到请求、调用 API、返回结果和错误信息。这对于排查“为什么查不到某家公司”这类问题至关重要。配置化除了 API 密钥可能还有其他可配置项如请求超时时间、默认返回结果数量、是否启用缓存等。这些都应通过配置文件或环境变量来管理增强灵活性。项目的技术选型通常是 Python 或 Node.js因为它们拥有丰富的 HTTP 客户端和 JSON 处理库且易于快速开发和部署。代码结构会遵循清晰的模块化原则将协议处理、工具定义、API 客户端、工具函数等分离确保可维护性和可测试性。3. 从零到一的部署与集成实操理解了原理接下来我们动手让它跑起来。假设你是一个开发者想要在本地 Claude Desktop 环境中使用这个工具。以下是详细的步骤和背后的考量。3.1 环境准备与依赖安装首先你需要一个基础的 Python 运行环境。项目推荐使用 Python 3.8 或更高版本。我强烈建议使用虚拟环境来管理依赖避免污染全局环境。# 1. 克隆项目代码到本地 git clone https://github.com/aicayzer/companies-house-mcp.git cd companies-house-mcp # 2. 创建并激活虚拟环境 (以 venv 为例) python -m venv .venv # 在 Windows 上 .venv\Scripts\activate # 在 macOS/Linux 上 source .venv/bin/activate # 3. 安装项目依赖 pip install -r requirements.txtrequirements.txt文件是关键它锁定了项目运行所需的所有第三方库。通常至少会包含mcp这是实现 MCP 服务器协议的核心 SDK。它提供了构建工具、资源以及启动服务器所需的所有框架代码。httpx或requests用于向 Companies House API 发起 HTTP 请求。httpx支持异步性能更好是现代项目的常见选择。pydantic用于数据验证和设置管理。它能让工具的参数定义和 API 响应解析变得非常清晰和类型安全。python-dotenv用于从.env文件加载环境变量方便管理 API 密钥等敏感信息。安装过程中如果遇到网络问题可以考虑使用国内的 PyPI 镜像源例如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。3.2 获取并配置 Companies House API 密钥这是访问数据的“通行证”。你需要前往 Companies House 开发者网站进行注册。访问注册页面打开https://developer.company-information.service.gov.uk/点击 “Get started” 或 “Sign in”。你需要创建一个账户可以使用个人邮箱。创建应用程序登录后在仪表板中创建一个新的应用程序。你需要提供一个应用名称例如 “My MCP Server”和描述。这个过程主要是为了获取 API 密钥和管理使用情况。获取 API 密钥创建应用后你会在详情页找到你的 “API key”。它通常是一长串由数字和字母组成的字符串。请务必像保护密码一样保护它不要上传到公开的代码仓库。配置密钥有两种主流方式环境变量推荐在终端中临时设置或写入你的 shell 配置文件如.bashrc,.zshrc。export COMPANIES_HOUSE_API_KEYyour_actual_api_key_here.env文件在项目根目录创建一个名为.env的文件内容如下COMPANIES_HOUSE_API_KEYyour_actual_api_key_here然后在你的服务器启动脚本中使用python-dotenv库来加载这个文件。这种方式便于项目化管理但切记要将.env添加到.gitignore文件中防止意外提交。实操心得Companies House 的免费套餐有速率限制通常是每分钟一定数量的请求。在开发测试阶段频繁调用很容易触发限流。建议在代码中为 HTTP 客户端添加适当的延迟或者实现一个简单的内存缓存对于相同的查询在短时间内返回缓存结果这既能提升响应速度也能避免不必要的 API 调用。3.3 配置 Claude Desktop 集成这是让工具生效的最后一步。Claude Desktop 允许你通过编辑配置文件来添加自定义的 MCP 服务器。定位配置文件macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件如果文件不存在就创建它。你需要添加一个mcpServers配置项。关键是指定你本地服务器的启动命令。{ mcpServers: { companies-house: { command: /absolute/path/to/your/.venv/bin/python, args: [ /absolute/path/to/your/companies-house-mcp/server.py ], env: { COMPANIES_HOUSE_API_KEY: your_actual_api_key_here } } } }参数详解command: 这里必须指向你虚拟环境中 Python 解释器的绝对路径。使用which python在激活的虚拟环境中命令可以获取。args: 启动参数列表第一个元素就是你的服务器主程序文件例如server.py的绝对路径。env: 在这里直接传递环境变量是一种方式但更安全的做法是在系统或用户层面设置或者如前所述使用.env文件。如果在这里写同样要注意配置文件的安全。重启 Claude Desktop保存配置文件后完全退出并重新启动 Claude Desktop 应用程序。验证连接重启后当你新建一个对话时Claude 应该会加载新的工具。你可以尝试问它“你现在可以使用 Companies House 工具吗” 或者直接下达指令“请搜索一下名为 ‘DeepMind’ 的英国公司。” 如果配置成功Claude 会识别到可用的工具并尝试调用。3.4 服务器启动与调试除了通过 Claude Desktop 集成你也可以直接运行服务器进行独立测试这对于调试非常有用。# 确保在项目目录下且虚拟环境已激活 python server.py如果服务器实现正确它会启动并开始监听来自 MCP 客户端的连接可能是 stdio 或 socket。你可以通过查看打印的日志信息来确认服务器是否正常启动以及是否成功加载了 API 密钥。一个常见的调试技巧是在开发初期可以先编写一个简单的测试脚本直接调用你封装的 API 函数确保能从 Companies House 拿到正确的数据然后再集成到 MCP 工具框架中。这有助于将网络问题、API 密钥问题与 MCP 协议逻辑问题分离开来排查。4. 核心工具使用详解与最佳实践成功集成后你将拥有一个强大的商业数据查询助手。了解每个工具的具体能力和最佳使用方式能让你事半功倍。4.1 公司搜索的精准策略search_companies工具是你的“雷达”。它的效果很大程度上取决于你输入的查询词。Companies House 的搜索 API 功能强大但有其逻辑。基本搜索直接输入公司全名或部分名称如 “British Airways”。AI 会调用工具并返回匹配列表。高级技巧使用公司编号如果你知道目标公司的唯一注册编号如 “01234567”直接用它搜索是最精准、最快速的能直达结果。模糊搜索与过滤搜索 API 支持近似匹配。对于拼写不确定或名称常见的公司可以结合地点信息。例如“Santander London” 会比单纯的 “Santander” 得到更精确的结果。在 AI 指令中你可以明确要求“搜索在曼彻斯特注册的、名称中包含 ‘Tech’ 的活跃公司。”理解返回结果工具返回的每条结果通常包含company_number: 公司编号是后续所有详细查询的钥匙。title: 公司名称。company_status: 状态如 “active”, “dissolved”。company_type: 类型如 “ltd”, “plc”。registered_office_address: 注册地址摘要。date_of_creation: 成立日期。注意事项搜索 API 有分页。默认情况下MCP 工具可能只返回第一页的若干条结果比如 20 条。如果你的查询结果很多可能需要结合使用items_per_page参数和后续的翻页逻辑如果工具支持。在向 AI 提问时如果寻找特定公司最好先通过搜索锁定其准确的公司编号。4.2 深度剖析公司档案get_company_profile是获取公司“体检报告”的工具。输入公司编号你将得到一份详尽的数据摘要。关键信息字段解读公司状态与类型company_status告诉你它是否在营、已解散或破产。company_type揭示了其法律结构私人股份有限公司、公众股份有限公司等。注册地址registered_office_address是公司的法定通讯地址对于法律文书送达至关重要。重要日期date_of_creation成立日、date_of_cessation停业日如有以及last_confirmation_statement_date最近一次确认声明日期勾勒出公司的生命时间线。财务概览accounts字段下的last_accounts提供了最近一个会计年度的关键财务数据如made_up_to结算日、type账目类型如 “full” 或 “small”。对于小型公司可能只公开简化的资产负债表。人员与管控officers链接了获取董事、秘书等人员的详细列表。persons_with_significant_control则揭示了公司的实际控制人这是现代公司治理和反洗钱审查的重点。使用场景示例快速尽调对接一个新供应商时让 AI 查询其公司档案快速确认其法律状态是否正常、注册地址是否真实、是否有最新的财务申报记录。竞品分析获取一系列竞争对手的公司类型和成立时间分析市场进入者的背景。网络关联分析结合董事姓名可以手动或通过其他工具进一步查询该董事在其他公司的任职情况绘制商业关系网络。4.3 人员与财务数据查询除了核心档案专用工具如get_officers和get_filing_history提供了更垂直的深度信息。get_officers获取人员列表返回当前及历史上的董事、秘书等任职人员。每条记录包含姓名、职务、任命日期、国籍、出生年份部分公开和住址服务地址。这里有一个重要细节Companies House 对个人住址信息有保护公开的通常是“服务地址”不一定是家庭住址。在利用这些数据时需注意隐私合规。get_filing_history获取提交历史这是公司的“活动日志”。每一次提交给 Companies House 的文件都会在这里留下记录包括年度账目、确认声明、董事变更通知、抵押登记等。通过分析提交历史的频率和类型可以判断公司的合规状况和重大事件时间线。例如频繁的董事变更可能暗示内部不稳定。最佳实践对于复杂的分析建议采用“分步查询”策略。先让 AI 用search_companies找到目标公司并获取编号然后用get_company_profile获取概览再根据需要用get_officers深入查看其管理团队。这样可以避免单次请求数据过载也让 AI 的思考过程更清晰。5. 常见问题排查与性能优化在实际使用中你可能会遇到一些问题。以下是一些典型问题及其解决方案。5.1 连接与认证失败问题现象可能原因排查步骤与解决方案Claude 提示“无法连接到工具”或“工具调用失败”。1. Claude Desktop 配置文件路径或命令错误。2. MCP 服务器程序本身启动失败如 Python 依赖缺失。3. 服务器启动后立即崩溃。1.检查配置文件确认 JSON 格式正确路径是绝对路径且无误。可以在终端手动运行配置中的command和args看能否启动服务器。2.查看日志在终端直接运行python server.py观察是否有明显的导入错误或运行时错误。这通常是依赖未安装或代码语法错误。3.验证环境变量在 Python 交互环境中尝试import os; print(os.getenv(‘COMPANIES_HOUSE_API_KEY’))确认密钥能被正确读取。工具可以调用但总是返回“认证错误”或“无效密钥”。1. Companies House API 密钥未设置或设置错误。2. 密钥已过期或被禁用。3. 环境变量未在正确的上下文中生效。1.确认密钥登录 Companies House 开发者门户确认密钥状态有效并复制完整的密钥字符串。2.检查加载方式如果通过.env文件确保文件在正确目录且代码中使用了load_dotenv()。3.重启终端/IDE有时环境变量需要新的会话才能生效。完全关闭 Claude Desktop 和终端再重新打开。5.2 数据查询异常问题现象可能原因排查步骤与解决方案搜索不到已知存在的公司。1. 公司已解散或名称变更。2. 搜索词不准确包含特殊字符或停用词。3. API 速率限制请求被静默拒绝。1.使用公司编号搜索这是最精确的方式。2.简化搜索词尝试只使用公司名中的核心词汇去掉 “Ltd”, “PLC”, “” 等。3.添加等待在代码中在连续请求间添加短暂延迟如time.sleep(0.5)避免触发每分钟的 API 限制。获取到的公司档案信息不全如缺少财务数据。1. 该公司可能因规模小而被豁免公开完整账目。2. 该公司可能尚未提交最近的财务报告。3. MCP 工具可能只提取了部分字段。1.理解数据限制这是 Companies House 数据本身的特性并非工具错误。小型公司或微型实体可能只提交简化的财务信息。2.检查 Filing History使用get_filing_history工具查看该公司最近提交了哪些类型的文件确认是否有 “AA” 结尾的账目文件。AI 回复“未找到相关工具”或调用错误的工具。1. Claude 的上下文未正确刷新。2. MCP 服务器提供的工具名称与 AI 预期不符。1.重启 Claude完全退出 Claude Desktop 并重新启动这是最有效的刷新 MCP 配置的方法。2.检查工具定义在 MCP 服务器代码中确认工具的名称name属性是search_companies,get_company_profile等标准名称。AI 客户端可能对工具有特定的命名预期。5.3 性能与稳定性优化建议当你要进行批量查询或将此工具用于生产环境时以下几点能显著提升体验实现请求缓存对于不常变化的数据如公司名称、注册地址可以在 MCP 服务器层面实现一个简单的内存缓存如使用functools.lru_cache或外部缓存如 Redis。为缓存设置合理的过期时间TTL例如公司档案缓存 24 小时人员列表缓存 12 小时。这能极大减少对 API 的调用提升响应速度并避免限流。优雅处理限流Companies House API 返回 429 状态码时表示请求过多。你的服务器代码应该捕获这个异常并实现指数退避重试机制而不是直接向用户报错。例如第一次重试等待 2 秒第二次等待 4 秒以此类推。结构化错误响应确保工具调用失败时返回给 AI 的错误信息是清晰、结构化的。例如不仅仅是 “API Error”而是 “Companies House API 请求失败认证无效 (HTTP 401)” 或 “未找到公司编号为 12345678 的记录”。这能帮助 AI 更好地理解问题并可能向用户给出更具体的操作建议。日志记录为服务器的关键操作接收请求、调用外部 API、返回结果、发生错误添加详细的日志记录。这不仅是调试的利器也能帮助你监控工具的使用情况和 API 的调用频率。6. 扩展思路与应用场景深化基础功能稳定后你可以考虑基于此项目进行扩展打造更强大的商业数据工具箱。6.1 功能扩展构建更丰富的工具集现有的工具提供了核心的“查”的功能。你可以围绕 Companies House 的数据开发更多增值工具监控工具创建一个watch_company工具输入公司编号和关注项如 “officer_change”, “filing”服务器可以定期通过后台任务检查 Companies House 的变动并通过 MCP 的“资源”功能或与其他通知服务如 Slack, Email集成主动推送变更提醒。批量查询与报告生成开发一个batch_company_profiles工具接受一个公司编号列表批量获取其档案并提取关键指标如状态、成立年限、是否有最新账目汇总成一个简明的 CSV 或 Markdown 格式报告供 AI 总结或直接下载。关联网络分析这是一个更高级的功能。工具find_network可以输入一个董事姓名首先搜索该姓名担任职务的所有公司然后递归地获取这些公司的其他董事从而绘制出一个局部的人物-公司关联网络图。这需要谨慎处理重名问题和 API 调用次数。6.2 与其他数据源集成Companies House 的数据是金矿但与其他数据源结合能产生更大价值。你的 MCP 服务器可以成为一个“聚合网关”。结合地理编码将公司的注册地址通过如 Google Maps Geocoding API 或 OpenStreetMap Nominatim 转换为经纬度坐标。这样AI 就可以回答诸如“找出我办公室 10 公里范围内所有的科技公司”这类问题。关联新闻与舆情在获取公司档案后调用新闻 API如 GDELT 或特定财经新闻源搜索该公司近期的相关新闻一并提供给 AI 进行综合判断。财务数据深化对于公开了完整财务报告PDF/XBRL的公司可以集成 OCR 或 XBRL 解析工具提取更详细的利润表、资产负债表数据进行简单的财务比率计算。6.3 部署与团队共享为了让团队其他成员也能使用你需要考虑部署方案容器化使用 Docker 将你的 MCP 服务器、Python 环境、依赖一起打包成一个镜像。这确保了运行环境的一致性。Dockerfile 会包含从安装 Python、复制代码、安装依赖到设置启动命令的所有步骤。进程管理在服务器上使用像 systemd 或 Docker Compose 来管理容器确保服务在崩溃后能自动重启并方便地查看日志。集中配置将 API 密钥等敏感信息通过 Docker Secrets 或云服务商提供的密钥管理服务来管理而不是写在配置文件里。团队配置分发你可以为团队提供一个标准化、预配置好的 Claude Desktop 配置文件片段团队成员只需将其合并到自己的配置中即可。或者如果你部署了一个 HTTP 模式的 MCP 服务器可以提供一个统一的服务器地址供大家连接。这个项目从一个简单的数据连接器出发其潜力在于成为你智能工作流中的一个核心组件。通过它你不仅是在查询数据更是在构建一个理解商业实体的认知层。随着你不断扩展其能力和集成范围它所能提供的洞察和支持将远远超出一开始的数据查询本身。