Planhat MCP

说明

如果托管连接器的 OAuth 或自定义连接器设置造成不便，Planhat MCP 可使用标准 API 令牌为你提供直接的本地连接。无需托管服务，也没有第三方服务介入 AI 与客户数据之间。

查看实际效果

你：“哪些公司本季度有许可证续期？”

**Claude：**通过本地 MCP 服务查询 Planhat，并返回符合条件的公司及其续期详情。

你可以让 Claude 列出记录、查看客户背景信息、创建跟进任务，或直接在对话中更新 Planhat。

在 Claude Desktop 中安装

下载一个文件，双击并粘贴令牌即可。无需终端、配置文件、代码，也无需预先安装任何内容。

1. 下载 .mcpb 文件。
2. 双击下载的文件。Claude Desktop 会打开安装弹窗。
3. 检查弹窗内容，然后点击 安装。
4. 如果你还没有 Planhat API 令牌，请创建一个：在 Planhat 中前往 Settings > Service Accounts (Private Apps) > API Access Token。此操作需要管理员权限。
5. 将令牌粘贴到令牌栏中。令牌会存储在系统钥匙串中，不会写入磁盘上的文件。
6. 可选：勾选 只读模式 或 禁用删除工具，以限制 AI 可以执行的操作。
7. 向 Claude 提问：“列出我排名前 3 的 Planhat 公司。” 如果得到回答，就表示完成了。

如果双击无法打开 Claude Desktop，请使用 Settings > Extensions > Advanced settings > Install Extension，然后选择下载的文件。

每个版本还包含 planhat-mcp.mcpb.sha256。若要在 macOS 或 Linux 上验证下载文件，请将两个文件放在同一目录中并运行：

shasum -a 256 -c planhat-mcp.mcpb.sha256

从手动安装切换？ 请先从 claude_desktop_config.json 中删除旧的 planhat 条目，否则每个工具都会显示两份。

手动安装

适用于 Claude Desktop 以外的 MCP 客户端，或希望从代码检出目录运行的情况。需要安装 Node.js 18 或更高版本。

1. 获取代码并构建服务：

git clone https://github.com/da-troll/Planhat-MCP.git ~/planhat-mcp
cd ~/planhat-mcp
npm install
npm run build

2. 添加 Planhat 令牌：

cp .env.example .env
open .env        # paste your token after PLANHAT_TOKEN= and save

令牌只会保存在你计算机上的那个文件中。请像对待密码一样妥善保管。

3. 在客户端的 MCP 配置中注册服务（Claude Desktop：claude_desktop_config.json；Cursor：.cursor/mcp.json），并将 YOUR-USERNAME 替换为你的用户名：

{
  "mcpServers": {
    "planhat": {
      "command": "node",
      "args": ["/Users/YOUR-USERNAME/planhat-mcp/dist/server.js"]
    }
  }
}

重启客户端，并使用上面相同的问题进行测试。

Claude 可以用它做什么

涵盖 12 种 Planhat 资源类型的 60 个工具。每种资源都支持相同的五种操作：list、get、create、update、delete。

资源	内容
公司	客户账户
联系人（最终用户）	客户的联系人
商机	销售／扩展交易
备注	账户的记录备注
对话	所有记录的联系信息：电子邮件、通话、备注、工单
用户	Planhat 中的团队成员
资产	与客户关联的产品／对象
问题	Bug 和功能请求
工单	支持工单
任务	待办事项和计划活动
许可证	经常性收入记录
发票	账单记录

Claude 只会执行你要求的操作，而你创建的令牌决定了它能够访问哪些内容。只读令牌会让整个连接器变为只读。

可选加固

无论连接的 AI 收到什么请求，这两个开关都能限制它的操作。打包安装时，可在安装弹窗中通过复选框设置；手动安装时，可将任一设置添加到 .env 文件中：

设置	效果
PLANHAT_READ_ONLY=1	仅提供 list/get 工具；无法更改 Planhat 中的任何内容。
PLANHAT_DISABLE_DELETE=1	所有功能均可使用，但无法删除记录。

每个工具也都包含标准 MCP 注解（readOnlyHint、destructiveHint），因此，按工具调整权限提示的客户端（破坏性调用前询问，读取操作自动批准）可以获取正确的信号。是否以及何时提示始终由客户端决定；上述开关和 Planhat 令牌本身的权限（参见 SECURITY.md）才是硬性限制。

仓库布局

planhat-mcp/
├── README.md                  ← you are here
├── manifest.json              ← .mcpb bundle definition (one-click install)
├── package.json               ← dependencies, scripts, version
├── package-lock.json          ← pinned dependency versions
├── tsconfig.json              ← TypeScript config
├── .env.example               ← token template for manual installs
├── .mcpbignore                ← what stays out of the bundle
├── src/
│   ├── index.ts               ← entry point: load config, serve over stdio
│   ├── server.ts              ← registers tools, applies gates + annotations
│   ├── tools.ts               ← all 60 tool definitions
│   ├── http.ts                ← Planhat REST client
│   └── env.ts                 ← .env loader for manual installs
├── tests/
│   ├── tools.test.ts          ← offline tests for all 60 tools
│   └── http.test.ts           ← HTTP layer: timeout, errors, delete cases
├── AGENTS.md                  ← handbook for AI coding agents
├── CLAUDE.md → AGENTS.md      ← same file, Claude's preferred name
├── LICENSE                    ← MIT
├── CHANGELOG.md               ← release history
├── SECURITY.md                ← token handling & reporting issues
├── CONTRIBUTING.md            ← how to add tools or fix bugs
└── .github/workflows/
    ├── ci.yml                 ← typecheck + tests + bundle gate on every push
    └── release.yml            ← GitHub release with .mcpb asset on version tags

发布的打包文件仅包含五个文件：manifest.json、dist/server.js（一个无依赖构建文件）、assets/icon.png、LICENSE 和 README.md。

故障排除

症状	可能的原因和解决方法
双击 .mcpb 没有任何反应，或“安装”按钮呈灰色	更新到较新的 Claude Desktop；较旧版本早于一键安装 .mcpb 扩展的功能。也可以通过 Settings > Extensions > Advanced > Install Extension 安装。
每个 Planhat 工具都出现两次	同时安装了打包版本和旧的手动配置项。请从 claude_desktop_config.json 中移除 mcpServers.planhat。
Claude 提示没有 Planhat 工具	Claude Desktop 只会在启动时读取配置。请彻底退出后重新打开，并检查 JSON 中没有多余的尾随逗号。
工具结果中出现 HTTP 401 Unauthorized	令牌错误、已过期或已轮换。请粘贴新的令牌。
PLANHAT_TOKEN is not set	打包安装：重新打开扩展的设置并填写令牌。手动安装：服务器旁没有 .env 文件，请重新执行手动安装步骤 2。
command not found: node（手动安装）	安装 Node.js 18 或更高版本，或将 command 指向 node 二进制文件的完整路径。
工具可以运行，但返回 []	通常这不是错误：对于你设置的筛选条件，该 Planhat 资源确实为空。

面向工程师

npm install          # install dependencies
npm test             # offline test suite (never touches the live API)
npm run typecheck    # TypeScript type checking
npm run build        # produce dist/server.js
npm start            # run the built server over stdio

在本地运行 npm run build && npx -y @anthropic-ai/[email protected] pack . planhat.mcpb，即可构建一键安装包。

架构说明、API 注意事项和贡献规则请参阅 AGENTS.md 和 CONTRIBUTING.md。端点路径已于 2026 年 7 月对照 Planhat 在线 API 验证。值得注意的是，Planhat 没有 /notes 或 /activities REST 端点；备注和工单在底层都属于 /conversations（完整说明请参阅 AGENTS.md）。

许可证

MIT。随意使用，不提供任何担保。