ITM Platform

ITM Platform MCP 服务

通过模型上下文协议将 ITM Platform 连接到 AI 助手。ITM Platform MCP 服务让兼容 MCP 的客户端能够搜索项目、查看预算、汇总项目组合状况、创建任务、记录风险和问题，并使用你的 ITM Platform 权限更新项目详情。

它可与 Claude、VS Code、Cursor、OpenAI Codex、Windsurf、JetBrains AI Assistant 以及其他支持 MCP 的客户端配合使用。

• 公开文档：developers.itmplatform.com/mcp
• npm 软件包：@itm-platform/mcp-server
• 托管 MCP URL：https://api.itmplatform.com/v2/_/mcp/

快速开始

使用 OAuth 连接托管服务

如果你的 AI 客户端支持远程 MCP 服务，请使用托管服务。无需安装任何内容：添加 URL，使用你的 ITM Platform 账户登录，然后批准所请求的访问权限。

claude mcp add --scope user --transport http itm-platform https://api.itmplatform.com/v2/_/mcp/

对于其他 MCP 客户端，请使用此远程 URL：

https://api.itmplatform.com/v2/_/mcp/

对于大多数用户，推荐使用 OAuth 设置，因为你的 AI 客户端永远不会看到你的 ITM Platform 密码或 API 密钥。

添加服务后，打开 AI 客户端，在支持斜杠命令的地方输入 /mcp，选择 itm-platform，并按提示完成 ITM Platform OAuth 登录。

使用 API 密钥进行本地连接

如果你倾向于在本地运行服务、在防火墙后工作，或需要连接到可自托管的 ITM Platform 实例，请使用 npm 软件包。

npx @itm-platform/mcp-server

你的 MCP 客户端必须向服务传递以下环境变量：

变量	值
ITM_API_URL	https://api.itmplatform.com
ITM_COMPANY	你的公司／账户标识
ITM_API_KEY	你从 ITM Platform 获取的个人 API 密钥

stdio 配置示例：

{
  "mcpServers": {
    "itm-platform": {
      "command": "npx",
      "args": ["@itm-platform/mcp-server"],
      "env": {
        "ITM_API_URL": "https://api.itmplatform.com",
        "ITM_COMPANY": "{your-account}",
        "ITM_API_KEY": "your-api-key"
      }
    }
  }
}

要创建 API 密钥，请登录 ITM Platform，打开 My Profile，然后在 API Key 部分生成密钥。

配置本地服务后，重启 AI 客户端，并使用 /mcp 或客户端的 MCP 服务列表确认 itm-platform 已连接。

Agent 可以做什么？

从简单查询到完全自动化的跨系统工作流，MCP 解锁了日益强大的用例。

快速查询 —— 提出问题，获取答案：

“我的项目组合中有哪些未关闭的风险？”

多步分析 —— Agent 串联多个工具并综合结果：

“检查本季度结束的每个项目。标记存在预算超支、未关闭的高影响风险或任务完成率低于 60% 的项目。”

自动化批量操作 —— Agent 跨项目读取信息、做出决策并写入数据：

“对于所有仍处于 Planning 状态且开始日期已过的项目，将状态更新为 Execution，并创建一项分配给项目经理的启动检查清单任务。”

定时智能分析 —— Agent 无需人工提示，按计划运行；每周一提取逾期任务，并按项目经理分组，将摘要发布到 Slack。

跨系统编排 —— 将 ITM Platform 的 MCP 与其他 MCP 服务（GitHub、Slack、Google Calendar、电子邮件）结合使用。开发人员合并 PR 后，Agent 会找到对应的 ITM Platform 任务并将其标记为已完成；如果项目达到 100%，则起草结项摘要并发送电子邮件给项目群经理。

MCP 服务以你的身份进行身份验证，调用 ITM Platform API，并且只返回你的 ITM Platform 账户有权访问的数据。

功能

该服务提供 47 个 MCP 工具、6 个资源和 4 个提示词模板。

读取工具

工具	功能
search_projects	按名称、状态、类型或日期范围查找项目
get_project	获取项目详情，包括子组件数量和可选的预算
search_services	按名称、状态、类型或日期范围查找服务
get_service	获取服务详情，包括子组件数量和可选的预算
list_project_tasks	分页列出项目的任务
get_task	获取单个任务的完整详情
search_tasks	按名称、状态、负责人、类别或日期范围搜索所有项目中的任务
get_project_budget	获取预算、实际数据、收入、成本和利润率信息
get_project_purchases	分页列出项目的采购订单
get_project_revenues	分页列出项目的收入条目
get_project_risks	分页列出项目风险
get_project_issues	分页列出项目问题
get_risk	获取单个风险的完整详情，包括缓解和应急计划
get_issue	获取单个问题的完整详情，包括解决方案和影响字段
list_task_progress	列出任务的进度（跟进）历史记录
get_task_effort	获取任务按团队成员和专业类别划分的工作量明细；也可用作任务团队列表
get_project_progress	获取项目进度报告：预期、基准和实际曲线；可选获取完整的项目 Seguimiento 条目
list_service_activities	分页列出服务的活动
get_service_purchases	分页列出服务的采购订单
get_service_revenues	分页列出服务的收入条目
aggregate_portfolio	对项目组合数据进行分组和汇总
query_datamart	运行经过验证的 DataMart 查询，进行高级分析
search_users	查找用户和团队成员；返回 IsNonLoginUser，以便使用 UserId 指定非登录用户（EmailAddress 为空）
get_user	获取用户详情
get_reference_data	获取状态、类型、优先级和其他参考列表
get_custom_fields	获取帐户中适用于项目、任务、风险、问题、服务、活动、采购或收入的自定义字段定义
get_custom_field_options	获取下拉式自定义字段的可选项

写入工具

工具	功能
create_project	创建项目（瀑布式或看板式）；项目会采用账户默认状态，并将创建者设为项目经理
create_task	添加任务、里程碑（KindId 1）或汇总任务（KindId 2）；ParentId 用于在瀑布式项目中构建甘特图层级；TaskManagers/TaskMembers 可通过用户名或数字 UserId 分配用户（非登录用户只能使用 ID）
update_task	更新任务状态、日期、类型和父级等字段；TaskManagers/TaskMembers 可通过用户名或数字 UserId 添加负责人（仅添加，不会移除）
create_task_progress	报告任务进度（百分比、评估、备注），并执行完整的副作用
update_task_progress	更新现有的任务进度条目
update_task_effort	为任务的每位负责人设置预计（计划）工时；已确认的工时和计费数据会保留
log_time_entry	记录一位用户在某个日期为任务实际投入的工时；将该工时加到当日总计或替换当日总计，并返回更新前后的总计
create_project_progress	创建项目级进度（Seguimiento）条目：百分比、评估和状态描述；进度达到 100% 时会自动关闭项目
update_project_progress	更新现有的项目进度条目
create_risk	记录项目风险
update_risk	更新风险状态、概率、影响、级别以及缓解或应急计划等字段
create_issue	记录项目问题，必须指定问题类型和状态
update_issue	更新问题状态、类型和解决方案等字段
update_project	更新项目名称、状态、日期和优先级等字段
create_service	创建服务；服务会采用账户默认状态
update_service	更新服务名称、状态、日期和优先级等字段
create_activity	为服务添加活动（活动以平铺列表形式呈现）
update_activity	更新活动状态和日期等字段
bulk_update_task_status	在单次调用中，将项目中最多 100 个任务设为同一状态
bulk_update_activity_status	在单次调用中，将服务中最多 100 个活动设为同一状态

写入操作会通过 ITM Platform REST API 确认已保存的状态。DataMart 支持的搜索结果最长可能需要 60 秒才能反映最近的写入。

验证失败时，会返回 REST 提供的可执行错误消息，而非仅返回 HTTP 状态。

数据源路由

只要 DataMart 中有相应数据，读取就会使用 DataMart（不占用配额，覆盖整个项目组合）；REST 仅用于 DataMart 缺少的数据、单条记录的权威读取（get_task）、写入后的回读以及参考数据。写入始终使用 REST。DataMart 纳入新数据集后，相应的 GET 工具必须迁移到 DataMart。完整规则和当前路由图见：zz_Specifications/progress-history-reads-from-datamart.md。

如果账户定义了自定义字段，每个会话都会补充账户级上下文：服务端会在 MCP 初始化说明和 query_datamart 工具描述中列出 DataMart 中实际使用的 customFields 键，让 Agent 无需事先发现即可读取和筛选自定义字段值。

资源和提示词

资源为 AI 客户端提供只读上下文，例如 DataMart 架构和项目日历。提示词模板为常见分析任务提供引导式工作流：

提示词	用途
/project_status	汇总单个项目的健康状况、任务、风险、问题和预算
/portfolio_overview	分析项目组合状态、方法、预算和交付模式
/team_workload	查看任务分配和工作量模式
/risk_analysis	评估风险敞口、问题和预算影响

身份验证和权限

MCP 服务使用与 ITM Platform 相同的身份和权限模型。

连接方式	身份验证	适用场景
托管 HTTP	OAuth 2.1 with PKCE	大多数用户和托管式 AI 客户端
本地 stdio	ITM Platform API key	本地执行、防火墙网络和可自托管环境

OAuth 会话使用以下作用域：

作用域	允许的操作
mcp:read	只读工具，例如搜索、获取、列出、聚合和查询
mcp:write	只读工具，以及创建和更新工具

API key 会话使用生成该密钥的 ITM Platform 用户的全部权限。

许可证访问权限：

许可证	MCP 访问权限
Company Admin	完整的读写权限
Full User	完整的读写权限
Project Manager	对所管理项目的读写权限
Team Member	禁止访问

你的 AI 助手不会收到你的 ITM Platform 密码或 API key。项目数据会返回给你选择的 AI 客户端，因此，AI 提供商的数据处理政策适用于其处理的任何数据。

客户端设置

请参阅公开文档，了解特定客户端的设置方法：

• Claude Code、Claude Desktop、VS Code、Cursor、Codex、Windsurf 和 JetBrains
• 使用 OAuth 连接
• 使用 API key 连接
• 故障排除

对于任何兼容 MCP 的客户端，两种连接方式对应的值如下：

方式	值
远程 URL	https://api.itmplatform.com/v2/_/mcp/
本地命令	npx @itm-platform/mcp-server

添加任一连接后，打开客户端的 MCP 命令或服务列表。在支持斜杠命令的客户端中，输入 /mcp，选择 itm-platform，并在提示时进行身份验证。

自托管

对于本地 stdio 服务，请配置 ITM_API_URL、ITM_COMPANY，以及 ITM_API_KEY 或 ITM_TOKEN。

对于使用 OAuth 的 HTTP 服务，请配置：

变量	说明
ITM_API_URL	ITM Platform API 网关 URL
PORT	HTTP 监听端口
ITM_AUTH_URL	用于令牌交换的 OAuth 授权服务器 URL
ITM_AUTH_PUBLIC_URL	向 AI 客户端公布的公开 OAuth URL
MCP_SERVER_URL	用作 OAuth 受众的公开 MCP 服务 URL
LOG_LEVEL	可选的 Pino 日志级别：debug、info、warn 或 error
ITM_AUDIT_ENABLED	设置为 true 时启用服务端审计日志
ITM_UI_URL	可选的 ITM Platform UI 基础 URL（例如 https://app.itmplatform.com）；设置后，create_project 会返回指向已创建项目的 uiUrl 深层链接

部署在反向代理后时，ITM_AUTH_URL 可以指向服务器到服务器的地址，而 ITM_AUTH_PUBLIC_URL 必须可供 AI 客户端访问。

开发

要求：

• Node.js 20 或更高版本
• npm

安装依赖项、运行测试并构建：

npm install
npm test
npm run build

运行 HTTP 开发服务器：

cp .env.sample .env
npm run dev

软件包入口点为 dist/server.js；npm 可执行文件为 mcp-server。

故障排除

如果 AI 客户端中没有显示工具，请确认服务器配置位于该客户端对应的正确文件中，重启客户端，并检查 npx @itm-platform/mcp-server 在本地设置中能否成功运行。

如果身份验证失败，请重新生成 API 密钥，或重新连接 OAuth 服务，以便客户端获取新的令牌。

OAuth 会话在下游返回 401 时，会自动重试一次：重新交换 OAuth bearer 令牌以获取新的会话令牌。这样可以处理会话令牌被外部失效的情况（例如，同时进行的浏览器登录导致令牌失效）。如果 401 错误仍然存在，则 OAuth bearer 令牌本身可能已过期，AI 客户端需要重新进行身份验证。

如果写入成功，但之后的搜索仍显示旧数据，请等待最多 60 秒。REST API 会立即确认写入，而 DataMart 搜索索引则会异步更新。

更多帮助

• MCP 文档：modelcontextprotocol.io
• ITM Platform 帮助：helpcenter.itmplatform.com
• ITM Platform 开发者文档：developers.itmplatform.com