Simpro MCP 服务器

非官方。 这是一个独立的第三方项目。它与 Simpro 无关联、未经其认可，也不受其支持。

让 AI 代理与您的 Simpro 账户协同工作。可以查找 Simpro 中几乎任何内容，汇总那些通常需要点击多个屏幕才能获取的数据。您用通俗英语提问；代理会为您在 Simpro 中执行查询和更改。

它可以访问 Simpro API 的每个部分，因此即使没有针对某件事的专用工具，代理仍然可以访问到它。

⚠️ 此工具不仅能读取，还能写入和删除。 它可以访问完整的 Simpro API，包括更新和删除记录的端点。驱动它的 AI 代理可能——由于失误或遵循错误指令——批量修改或删除您实时 Simpro 账户中的报价、工作、客户、目录项等，且无法撤销。它使用您提供的密钥或登录凭据所拥有的任何权限进行操作。不要将其交给您不信任的代理，不要让其无人值守地针对生产环境运行，并为其提供一个仅限其实际所需范围的 Simpro 登录/密钥。 如果您需要只读安全性，请创建一个具有只读权限的 Simpro 用户，并以该用户身份进行身份验证。

这是从我们内部使用的工具开发而来的，该工具位于我们自己的 MCP 网关之后。我们添加了一些额外功能，使其对社区更有用，但 mcbp 和 OAuth Broker 模式并非我们内部使用。

本软件按“原样”提供，不附带任何明示或暗示的保证。您自行承担运行风险；作者对因使用本软件而导致的任何损失、损害或对您的 Simpro 数据所做的更改不承担任何责任。

先决条件

• 对于 Claude Desktop 安装（选项 1）： 只需要 Claude Desktop 和一个 Simpro OAuth 应用——.mcpb 捆绑包自带运行时。

• 要从源代码运行或自行托管（选项 2 和 3）： Node.js 24 或更高版本以及 npm。

• 一个您可以访问的 Simpro build，以及在其中创建的 OAuth 应用（或旧版 API 密钥）——每种模式的部分都会说明其确切需要什么。

Related MCP server: ServiceTitan MCP Server

目录

• 安装到 Claude Desktop（简单方法）

  • 您需要从 Simpro 获取什么

  • 安装

  • 登录（OAuth 流程）

  • 其他身份验证方式

  • 从源代码本地运行

• OAuth Broker 模式（用于 AI 代理连接器）

• HTTP 代理模式（用于共享/托管设置）

• 我想要哪种模式？

• 连接客户端（配置片段）

• Broker 如何升级 Simpro 的登录

• 自行构建

1. 安装到 Claude Desktop（简单方法）

无需命令行，无需设置文件。您从 Claude Desktop 的扩展设置中安装 .mcpb 捆绑包，填写一个简短的表单，然后在浏览器中登录一次 Simpro。之后代理保持登录状态，您只需聊天即可。

您需要从 Simpro 获取什么

您使用 Simpro OAuth 应用进行身份验证，该应用通过 Simpro 自己的登录屏幕让您登录——这是推荐的方式。在 Simpro 的 设置 → 集成 → API → 新建 API 密钥（选择 OAuth /“授权码”应用程序）下创建一个，然后记下：

一个重要步骤： 在您的 Simpro OAuth 应用中，将 重定向 URI 设置为 http://localhost:8237/callback。这是您登录后 Simpro 将您送回的地方。它必须完全匹配。如果端口 8237 在您的机器上已被占用，请选择另一个端口，并在安装屏幕上设置匹配的 Auth 重定向端口——但注册的重定向 URI 必须使用相同的端口。

安装

1. 从 Releases 页面 下载最新的 simpro-mcp-server.mcpb 文件。

2. 在 Claude Desktop 中，打开 设置 → 扩展，点击 高级设置，然后 安装扩展（您可能首先需要在那里启用开发者/扩展安装）。选择您下载的 simpro-mcp-server.mcpb 文件。出现安装屏幕。

3. 填写：

   • Build URL 和 公司 ID

   • 身份验证模式——保持为 authorization_code（浏览器登录）。

   • 来自您的 Simpro OAuth 应用的 客户端 ID 和 客户端密钥。

   • 除非您注册了不同的端口，否则将 Auth 重定向端口 保持为 8237。

4. 点击安装。

登录（OAuth 流程）

代理第一次使用该工具时，浏览器选项卡会在 Simpro 登录屏幕打开。登录并批准访问。选项卡显示 “✓ 已授权”——关闭它并返回您的聊天。

只需一次登录即可。该工具会缓存刷新令牌，因此它在重启后保持登录状态，并且在令牌被撤销或过期之前不会再次提示您。如果发生这种情况，它只会再次打开登录选项卡。

就是这样——开始聊天并提出类似 “显示 Acme 的未结报价” 或 “工作 4521 上有什么？” 的问题。

页面大小 是安装屏幕上的一个可选设置。保持为 50。它只是限制一次返回多少行，这样大列表不会压垮单个答案——代理总是可以要求更多。

其他身份验证方式

安装屏幕上的 身份验证模式 字段提供三个选项：

保护您的凭据安全

您的客户端密钥、刷新令牌和任何 API 密钥由 Claude Desktop 存储，仅用于与您自己的 Simpro build 通信。任何拥有这些信息的人都可以以您授予的相同访问权限在 Simpro 中操作，因此不要将 .mcpb 安装或这些值分享给不应拥有该访问权限的人。如果凭据曾经暴露，请在 Simpro 中撤销 OAuth 应用或密钥，并创建一个新的。

从源代码本地运行

适用于开发人员，或任何从 Git 检出而不是 .mcpb 捆绑包运行的人。 如果您已安装上述扩展，可以跳过此部分。

1. 复制 .env.example → .env 并设置 SIMPRO_BASE_URL 和 SIMPRO_COMPANY_ID，以及 要么 SIMPRO_CLIENT_ID + SIMPRO_CLIENT_SECRET（用于浏览器登录或机器登录）要么 SIMPRO_API_KEY（旧版密钥）。

2. 身份验证模式根据您设置的内容自动确定——当客户端 ID 和密钥都存在时为 client_credentials，否则为 api_key。要强制浏览器登录，请设置 SIMPRO_AUTH_MODE=authorization_code。

3. npm install && npm run build && npm start——这通过 stdio 运行，与已安装的扩展相同。

对于浏览器登录（authorization_code），您可以预先使用 npm run login 登录一次——它会打开 Simpro 登录选项卡并将刷新令牌缓存到 .simpro-tokens.json。如果您跳过它，服务器只会在首次使用工具时运行相同的登录。有关完整脚本列表，请参阅 自行构建。

2. OAuth Broker 模式（用于 AI 代理连接器）

用于将 Simpro 作为真正的 连接器 连接到 AI 代理，其中每个人通过正常的 Simpro 登录屏幕自行登录 Simpro——无需共享密钥，无需个人设置文件。对于大多数在服务器上运行此工具的人来说，这就是您想要的模式。

这是提供的 Docker 设置默认使用的模式。 这是更安全的默认设置：服务器自行验证用户身份，而不是信任上游传递给它的凭据。它仍然应该位于终止 TLS 并将 PUBLIC_URL 路由到它的反向代理之后——但容器永远不会决定信任入站标头。

Simpro 自己的登录是 OAuth 2.0 设计，现代代理连接器不会直接连接。此服务器位于中间，将其提升到他们要求的 OAuth 2.1 标准——添加 Simpro 缺少的安全步骤，同时仍然移交给真正的 Simpro 登录。从用户的角度来看，这只是“点击连接，登录 Simpro”。它添加的确切步骤在下面的 Broker 如何升级 Simpro 的登录 中详细说明。

服务器位于 Simpro 之前并运行登录握手。用户在其代理中添加连接器，被发送到 Simpro 登录，从那时起，代理在 Simpro 中以该人的身份操作。他们的 Simpro 访问权限封装在代理持有的令牌中；服务器不保留登录数据库。

此模式需要公共 Web 地址和 Simpro OAuth 应用（在 Simpro 的 设置 → 集成 下创建）。在该 OAuth 应用中，将 重定向 URL 设置为您的公共地址后跟 /callback——例如 https://simpro.yourcompany.com/callback。

设置

在 SIMPRO_BASE_URL（以及可选的 SIMPRO_COMPANY_ID）之上，将这些设置为环境变量。

在此模式下不要设置 SIMPRO_API_KEY——服务器将拒绝启动。

3. HTTP 代理模式（适用于共享/托管部署）

适用于在服务器上运行、且由其他系统（例如 Cowork 或 Copilot 部署）处理登录的团队。在此模式下，服务器自身不持有任何 Simpro 密钥——每个请求都携带自己的登录凭据，由任何为你用户执行登录的系统附加。服务器只是将其透传给 Simpro。

⚠️ 不设计为面向公网。 此模式必须运行在网关或反向代理（MCP 网关、Context Forge，或类似 nginx/Traefik 的工具）之后，由后者终止 TLS 并对用户进行身份验证。它自身不做任何认证，也未针对直接暴露进行加固——切勿将其直接发布到互联网。容器默认不会发布到宿主机上；网关通过私有网络访问它。

要使用此模式，请设置 SIMPRO_TRANSPORT=proxy（随附的 Docker 配置默认使用更安全的代理模式，即上文所述）。如果你使用 Portainer 或 Context Forge 部署，请参阅 docs/deploy.md 了解堆栈布局。

你无需在此处设置 API 密钥——实际上，如果存在 API 密钥，服务器会拒绝启动，因为在此模式下，每个用户的登录凭据才是唯一应授予访问权限的东西。

重要——此模式自身不做任何检查。 请求携带的任何 Authorization 头都会被原样直接转发给 Simpro。服务器不会验证凭据是否有效、是否过期，或请求是否来自有权发起请求的人——只有 Simpro 才能决定凭据是否有效。这是有意为之：此模式假定其前面的层（网关或登录系统）已经对用户进行了身份验证，并附加了可信的头。仅在此类层之后运行此模式。 如果你直接暴露它，任何能访问到它的人都可以将其请求头原样传递给 Simpro。

设置项

这些以环境变量形式设置（在你的 .env 文件中或由你的容器平台设置）。

在此模式下不要设置 SIMPRO_API_KEY——服务器将拒绝启动。

你还可以调整单次返回的数据量：

4. 我该用哪种模式？

5. 连接客户端（配置片段）

Claude Desktop 的 .mcpb 安装（选项 1）会自行写入配置——你无需为此修改 JSON。以下片段适用于从源码检出运行或将客户端指向托管的代理/代理服务器。

Claude Desktop - 从源码以 stdio 方式运行

编辑 claude_desktop_config.json（设置 → 开发者 → 编辑配置）。将 command 指向 node，将 args 指向构建后的 dist/index.js，并将你的 Simpro 设置作为 env 传入：

{
  "mcpServers": {
    "simpro": {
      "command": "node",
      "args": ["/absolute/path/to/simpro-mcp/dist/index.js"],
      "env": {
        "SIMPRO_BASE_URL": "https://yourbuild.simprosuite.com",
        "SIMPRO_COMPANY_ID": "0",
        "SIMPRO_AUTH_MODE": "authorization_code",
        "SIMPRO_CLIENT_ID": "your-oauth-client-id",
        "SIMPRO_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

先构建（npm install && npm run build）。在 Windows 上使用带转义反斜杠的完整路径（"C:\\path\\to\\simpro-mcp\\dist\\index.js"）。对于旧版密钥，去掉 client id/secret，改为设置 "SIMPRO_API_KEY"（仅限 stdio）。

Claude Code - claude mcp add

从 CLI 注册相同的 stdio 服务器（在检出目录中运行，或使用绝对路径）：

claude mcp add simpro \
  --env SIMPRO_BASE_URL=https://yourbuild.simprosuite.com \
  --env SIMPRO_COMPANY_ID=0 \
  --env SIMPRO_AUTH_MODE=authorization_code \
  --env SIMPRO_CLIENT_ID=your-oauth-client-id \
  --env SIMPRO_CLIENT_SECRET=your-oauth-client-secret \
  -- node ./dist/index.js

将客户端指向托管的代理（选项 2）

代理在你的公共地址后运行后，将其添加为远程连接器——无需本地命令，也无需环境变量。在客户端中使用连接器/"添加自定义连接器"界面，并提供 MCP URL：

https://simpro.yourcompany.com/mcp

客户端会被引导到 Simpro 进行登录；无需其他配置。（选项 3 的 HTTP 代理以相同方式访问，但期望你的网关附加 bearer 令牌——它不能作为裸连接器添加。）

6. 代理如何升级 Simpro 的登录机制

本节面向对技术感兴趣或希望审查连接器安全性的人。使用上述三种模式时你无需了解这些内容。

现代代理连接器只连接符合 OAuth 2.1 标准的授权服务器。Simpro 的 OAuth 不支持 PKCE，也不支持这些连接器所使用的客户端身份方案。与其要求 Simpro 做出改变，代理选择站在其前面，自身充当一个符合 OAuth 2.1 标准的授权服务器，并在幕后静默地中继到 Simpro。具体来说，它增加了：

• PKCE（S256），由我们强制实施。 连接客户端必须在 /authorize 上发送代码挑战（code challenge），并在 /token 上证明它；不匹配即被拒绝。Simpro 本身不做 PKCE，因此代理（broker）才是实际执行方——弥补了纯 2.0 留下的授权码被盗漏洞。

• 现代客户端身份——不将共享密钥内置于客户端。 连接客户端通过两种标准方式之一告知代理其身份，代理接受给定客户端所使用的任何一种方式：

  • CIMD（客户端 ID 元数据文档）：client_id 是一个 URL，代理在每次请求时获取并验证它——它必须是自引用的，并列出正在使用的确切重定向地址。无需预先注册任何内容。该获取操作在反 SSRF 防护之后运行，因此该 URL 不能用于探测服务器的内部网络。

  • DCR（动态客户端注册，RFC 7591）：客户端可以 POST /register 预先创建自己的 client_id。代理在其元数据中公布此端点。注册是开放的（无需认证），因此有速率/大小限制，并在达到上限时淘汰最旧的条目；已注册的客户端会被持久化，以便在重启后仍然存在。客户端可以注册为公共（无密钥）或机密（代理颁发密钥，然后在令牌步骤要求提供）。

  无论哪种方式，下游客户端的身份都不会到达 Simpro：代理持有一个固定的 Simpro 注册，并以此身份进行中继。

• 精确重定向匹配。 客户端被送回到的地址必须与注册的地址逐字符匹配——而不仅仅是"以……开头"。

• 短生命周期、绑定受众的令牌。 客户端收到的令牌是代理颁发的，带有过期时间戳，并绑定到此特定服务器作为其受众。真正的 Simpro 令牌被加密（密封）在内部。代理不保留令牌数据库——每个令牌都是自包含的——并且它颁发的刷新令牌有 30 天的上限生命周期，因此泄露的令牌无法被无限重放。唯一的例外：由于 Simpro 在使用时会轮换刷新令牌（每次刷新都会消耗旧令牌），代理仅在内存中保存每次登录的当前上游刷新令牌，持续几分钟，这样丢失刷新响应的客户端就不必被迫重新登录。它永远不会写入磁盘；下一次成功刷新——确认客户端现在持有当前令牌——就会将其淘汰，而重启或几分钟的空闲也会清除它。

最终效果：代理与看起来像干净、现代的 OAuth 2.1 提供方的东西通信，用户仍然在真正的 Simpro 屏幕上登录，而 Simpro 流程中较弱的环节在中间得到了加固。整个交换仅在握手进行的几秒钟内于内存中关联，这就是为什么此模式必须作为单实例运行——不要将其放在负载均衡器后面。

自行构建

如果你是在处理代码而不是仅仅使用它：

npm install
npm run build        # compile
npm test             # run the unit tests
npm run login        # one-time browser sign-in (authorization_code); caches the refresh token
npm run build:mcpb   # produce the simpro-mcp-server.mcpb install file
npm start            # run it locally

npm run login 运行编译后的 dist/login.js，因此请先构建；它需要设置 SIMPRO_CLIENT_ID 和 SIMPRO_CLIENT_SECRET（参见上文从源码本地运行）。

有一个单元测试套件（npm test）覆盖纯确定性部分——搜索排名、输出格式化、行项目路径以及认证加密/存储辅助函数。没有 linter，也没有任何网络模拟，因此完全检查更改仍然意味着构建它并针对真实的 Simpro 账户进行尝试。架构说明和值得了解的 Simpro API 怪癖在 CLAUDE.md 中。