Procore Mcp Server

Procore MCP 服务

MCP 服务将完整的 Procore REST API 提供给 Claude 等 AI 助手。使用 TypeScript 和 Model Context Protocol SDK 构建。

适用于 Claude Desktop、Claude Code 和任何兼容 MCP 的客户端。

功能

构建时解析器会将 Procore 的 OpenAPI 规范转换为精简目录，然后为每个 API 操作自动生成独立的 MCP 工具。运行时，AI 可通过 7 个元工具发现并调用任意 Procore 端点：

工具	用途
procore_discover_categories	列出 API 类别及其端点数量
procore_discover_endpoints	列出某个类别中的端点
procore_search_endpoints	对所有端点进行全文搜索
procore_get_endpoint_details	获取端点的完整参数架构
procore_api_call	执行任意 Procore API 调用
procore_get_config	显示当前配置和身份验证状态
procore_set_config	设置运行时配置（company_id、project_id）

前提条件

• Node.js 18+
• Procore Developer Portal 账号
• OAuth 应用，授权类型为 Authorization Code
• 将重定向 URI 设置为 http://localhost

设置

git clone https://github.com/TylerIlunga/procore-mcp-server.git
cd procore-mcp-server
npm install

复制示例环境变量文件并填写凭据：

cp .env.example .env

PROCORE_CLIENT_ID=your_client_id
PROCORE_CLIENT_SECRET=your_client_secret
PROCORE_COMPANY_ID=your_company_id

默认情况下，服务会公开 7 个发现工具，每个 Procore 端点都通过 procore_api_call 调用。为每个端点注册专用工具会生成约 4.7 MB（约 120 万个 token）的工具定义， 超出当前任何模型的上下文窗口，因此该功能需选择启用：

PROCORE_TOOL_MODE=all

两种模式的覆盖范围相同，区别仅在于公开的工具列表大小。 如果切换到 all，且从 v2.0.0 之前的版本迁移，请参阅 data/tool-renames.json，查看旧工具名称到新工具名称的映射。

你需要将 Procore 的 OpenAPI 规范文件放在 specs/combined_OAS.json。由于文件较大（约 54 MB），仓库中不包含该文件。你可以从 Procore API 文档获取。

构建目录并编译 TypeScript：

npm run build

通过 Procore 进行身份验证（将打开浏览器进行 OAuth）：

npm run auth

启动服务：

npm start

Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "procore": {
      "command": "node",
      "args": ["/absolute/path/to/procore-mcp-server/dist/src/index.js"],
      "env": {
        "PROCORE_CLIENT_ID": "your_client_id",
        "PROCORE_CLIENT_SECRET": "your_client_secret",
        "PROCORE_COMPANY_ID": "your_company_id"
      }
    }
  }
}

Claude Code 配置

将以下内容添加到项目根目录下的 .mcp.json：

{
  "mcpServers": {
    "procore": {
      "command": "node",
      "args": ["/absolute/path/to/procore-mcp-server/dist/src/index.js"],
      "env": {
        "PROCORE_CLIENT_ID": "your_client_id",
        "PROCORE_CLIENT_SECRET": "your_client_secret",
        "PROCORE_COMPANY_ID": "your_company_id"
      }
    }
  }
}

项目结构

src/
  auth/       OAuth token exchange, refresh, storage
  api/        HTTP client with auth, rate limits, retries
  catalog/    Endpoint catalog loading, search, filtering
  tools/      MCP tool handlers and registration
scripts/
  generate-catalog.ts          Parse OAS into catalog
  generate-tools-manifest.ts   Generate per-endpoint MCP tools
  validate-catalog.ts          Validate catalog integrity
data/         Build output (committed): catalog.json, endpoint details, tools manifest
specs/        Source OAS file (gitignored — too large for the repo)

工作原理

1. 构建时：scripts/generate-catalog.ts 会解析约 54MB 的 Procore OpenAPI 规范（3,155 个操作），并生成精简的 data/catalog.json 以及 data/endpoint-details/ 中的各个端点详情文件。随后，scripts/generate-tools-manifest.ts 会生成工具清单，为每个 API 操作创建一个独立命名的 MCP 工具——共 2,929 个，已合并同一路径上旧版本的重复项。

   每个生成的工具都包含结构化描述，说明它操作的对象、适用场景、需要先解析的父级 ID、返回内容以及失败方式。Procore 已弃用的端点会在描述中注明弃用日期，并使用 (Deprecated) 标题。交互式 /oauth/* 端点不会注册为工具——该流程由 npm run auth 负责——但仍可通过 procore_api_call 访问。

2. 身份验证：运行一次 npm run auth，在浏览器中完成 OAuth 流程。令牌会保存到 ~/.procore-mcp/tokens.json，并在过期时自动刷新。

3. 运行时：MCP 服务会加载目录并注册 7 个发现工具（当 PROCORE_TOOL_MODE=all 时，还会注册完整的逐端点工具集）。AI 助手调用工具时，服务会将其映射到正确的 Procore API 端点，注入身份验证标头，处理速率限制和分页，并返回响应。

灵感来源

本项目旨在帮助我女朋友，她是一名每天都使用 Procore 的建筑工程师。

许可证

MIT