Planfix MCP Server

Planfix MCP Server

此 MCP 服务可与 Planfix API 集成，让 Model Context Protocol（MCP）客户端能够与 Planfix CRM 和任务管理系统交互。

功能

• 潜在客户管理（创建、搜索、转换为任务）
• 搜索潜在客户时可复用已知的 clientId，跳过联系人查询
• 联系人和公司管理
• 任务管理（创建、搜索、评论）
• 报告生成与管理
• 使用 Planfix REST API v2.0（API 文档）
• 通过 Bearer 令牌进行身份验证

配置

访问 Planfix API 需要设置以下环境变量：

• PLANFIX_ACCOUNT – Planfix 账户名称（例如 yourcompany）
• PLANFIX_TOKEN – 具有必要权限的 Planfix API 令牌
• PLANFIX_BASE_URL –（可选）覆盖 REST API 基础 URL。默认为 https://<PLANFIX_ACCOUNT>.planfix.com/rest/。用于 .ru 和其他区域的安装，例如 https://yourcompany.planfix.ru/rest/
• PLANFIX_ACCOUNT_URL –（可选）覆盖用于面向用户的链接（任务／联系人／用户页面）的 Web 来源地址。默认为去掉末尾 /rest/ 的 PLANFIX_BASE_URL
• PLANFIX_FIELD_ID_EMAIL – 邮箱的自定义字段 ID
• PLANFIX_FIELD_ID_EMAIL_ADDITIONAL –（可选，无默认值）用于存储其他邮箱地址（多值）的数字型自定义字段 ID。必须指向你在账户中创建的真实多值自定义字段；系统的备用邮箱字段 ID 124 不能作为写入目标。未设置时，将禁用其他邮箱地址的存储（仍可通过系统字段进行匹配）。Planfix 的系统备用邮箱字段（additionalEmailAddresses）无法通过 REST API 写入，因此其他邮箱地址会写入此自定义字段；设置此项后，任何邮箱搜索的匹配都会同时使用系统字段（筛选器类型 4221）和此自定义字段（筛选器类型 4101）
• PLANFIX_FIELD_ID_PHONE – 电话号码的自定义字段 ID
• PLANFIX_FIELD_ID_TELEGRAM – 设置任意值即可使用系统 Telegram 字段
• PLANFIX_FIELD_ID_TELEGRAM_CUSTOM – 使用自定义字段时的 Telegram 自定义字段 ID
• PLANFIX_FIELD_ID_CLIENT – 客户的自定义字段 ID
• PLANFIX_FIELD_ID_MANAGER – 经理的自定义字段 ID
• PLANFIX_FIELD_ID_AGENCY – 代理机构的自定义字段 ID
• PLANFIX_FIELD_ID_LEAD_SOURCE – 潜在客户来源的自定义字段 ID
• PLANFIX_FIELD_ID_LEAD_SOURCE_VALUE – 默认潜在客户来源的值 ID
• PLANFIX_FIELD_ID_PIPELINE – 流程的自定义字段 ID
• PLANFIX_FIELD_ID_TAGS – 任务标签的自定义字段 ID
  • 缺失的标签名称会自动添加到目录中
• PLANFIX_FIELD_ID_LEAD_ID – 外部潜在客户 ID 的自定义字段 ID
• PLANFIX_LEAD_TEMPLATE_ID – 潜在客户任务模板的 ID
• PLANFIX_TASK_TITLE_TEMPLATE – 默认潜在客户任务标题的模板（例如 {name} - client's task）

config.yml

也可以通过 config.yml 配置自定义字段。默认路径为 ./data/config.yml。可通过 --config=/abs/path/config.yml CLI 标志或 PLANFIX_CONFIG 环境变量覆盖。使用自定义配置时，也可以指定 其他 Planfix 账户：

PLANFIX_CONFIG=/etc/planfix-mcp.yml PLANFIX_ACCOUNT=demo \
npx @popstas/planfix-mcp-server

proxyUrl: "http://localhost:8080"

webhook:
  enabled: false
  url: "https://example.com/hook"
  token: "<token>"
  skipPlanfixApi: false

leadTaskFields:
  - id: "456"
    name: "id сделки"
    argName: lead_id
    type: number
contactFields:
  - id: "123"
    name: "Резидентство"
    argName: resident
    type: enum
    values: ["резидент", "нерезидент", "иное"]
userFields:
  - id: "789"
    name: "Департамент"
    argName: department
    type: string

proxyUrl 会将所有 Planfix REST API 调用（包括工具请求）通过指定的 HTTP 代理转发。

合并配置时，config.yml 中的值会按 id 覆盖旧版环境变量中匹配的条目。planfix_search_manager 工具会逐一请求此列表中的用户自定义字段，以便在响应中提供其值。此工具支持通过 email 或数字型 id 搜索经理，因此仅有标识符时也能进行查询。

Chat API

若要通过聊天消息创建任务，请在 config.yml 中添加 chatApi 块：

chatApi:
  useChatApi: true
  chatApiToken: "<token>"
  providerId: "<id>"
  baseUrl: "https://<account>.planfix.com/webchat/api"

• chatApiToken – Planfix Chat API 请求的令牌。
• providerId – 在 Planfix 中配置的聊天提供商标识符。
• useChatApi – 启用 Chat API 集成。设为 true 时，任务创建流程如下：
  1. 通过 Chat API 创建聊天，并发送初始消息。
  2. getTask 会获取新任务的 taskId。
  3. 后续更新通过 REST API 完成。
• baseUrl – Chat API 调用的基础 URL。默认为 https://<account>.planfix.com/webchat/api。

Webhook

若要在创建或更新任务前，将线索任务负载发送到 webhook， 请在 config.yml 中添加 webhook 块：

webhook:
  enabled: true
  url: "https://example.com/hook"
  token: "<token>"
  skipPlanfixApi: false

• enabled – 是否将线索任务负载发送到 webhook URL。
• url – webhook 端点 URL。
• token – 作为 token 附加到 JSON 负载中的共享密钥。
• skipPlanfixApi – 设为 true 时，webhook 响应必须包含 taskId，并且 跳过 Planfix REST API 调用。

调试

npx @modelcontextprotocol/inspector node d:/projects/expertizeme/planfix-mcp-server/dist/index.js

日志记录

设置 LOG_LEVEL=debug 以启用详细的缓存日志。日志写入 data/mcp.log。

清除缓存

运行 npm run cache-clear，以删除存储在 data/planfix-cache.sqlite3 中的所有缓存 Planfix API 响应，并删除对象缓存文件 data/planfix-cache.yml。

MCP 配置示例（NPX）

{
  "mcpServers": {
    "planfix": {
      "command": "npx",
      "args": [
        "-y",
        "@popstas/planfix-mcp-server"
      ],
      "env": {
        "PLANFIX_ACCOUNT": "yourcompany",
        "PLANFIX_TOKEN": "your-api-token",
        "PLANFIX_FIELD_ID_EMAIL": "123",
        "PLANFIX_FIELD_ID_PHONE": "124",
        "PLANFIX_FIELD_ID_TELEGRAM": "1",
        "PLANFIX_FIELD_ID_TELEGRAM_CUSTOM": "125",
        "PLANFIX_FIELD_ID_CLIENT": "126",
        "PLANFIX_FIELD_ID_MANAGER": "127",
        "PLANFIX_FIELD_ID_AGENCY": "128",
        "PLANFIX_FIELD_ID_TAGS": "129",
        "PLANFIX_FIELD_ID_LEAD_ID": "130",
        "PLANFIX_LEAD_TEMPLATE_ID": "42",
        "PLANFIX_TASK_TITLE_TEMPLATE": "{name} - работа с клиентом"
      }
    }
  }
}

使用方法

运行服务

设置所需的环境变量后运行服务。示例（使用 npx）：

PLANFIX_ACCOUNT=yourcompany \
PLANFIX_TOKEN=your-api-token \
PLANFIX_FIELD_ID_EMAIL=123 \
PLANFIX_FIELD_ID_PHONE=124 \
PLANFIX_FIELD_ID_TELEGRAM=1 \
PLANFIX_FIELD_ID_TELEGRAM_CUSTOM=125 \
PLANFIX_FIELD_ID_CLIENT=126 \
PLANFIX_FIELD_ID_MANAGER=127 \
PLANFIX_FIELD_ID_AGENCY=128 \
PLANFIX_FIELD_ID_LEAD_SOURCE=129 \
PLANFIX_FIELD_ID_LEAD_SOURCE_VALUE=130 \
PLANFIX_FIELD_ID_PIPELINE=131 \
PLANFIX_FIELD_ID_LEAD_ID=132 \
PLANFIX_FIELD_ID_TAGS=133 \
PLANFIX_LEAD_TEMPLATE_ID=42 \
PLANFIX_TASK_TITLE_TEMPLATE="{name} - работа с клиентом" \
npx @popstas/planfix-mcp-server

若要通过 Server-Sent Events（SSE）运行服务，请使用 planfix-mcp-server-sse 命令：

PLANFIX_ACCOUNT=yourcompany \
PLANFIX_TOKEN=your-api-token \
planfix-mcp-server-sse

使用 Planfix 客户端

Planfix 客户端提供了一种便捷方式，可直接从命令行与 Planfix API 交互。

先决条件

请确保已在 .env 文件中设置以下环境变量：

PLANFIX_ACCOUNT=your-account
PLANFIX_TOKEN=your-api-token

基本命令

1. 测试连接

   npm run planfix test
   

2. 发起 GET 请求

   npm run planfix get user/current
   

3. 携带数据发起 POST 请求

   npm run planfix post task/ --data '{"name":"Test Task","description":"Test Description"}'
   

4. 搜索对象

   npm run planfix post object/list --data '{"filters":[{"type":1,"operator":"equal","value":"Продажа"}]}'
   

工具参考

planfix_create_sell_task

• 使用有关代理机构和员工的文本信息创建销售任务。
• 根据提供的字符串自动解析客户、父级线索任务、负责人和代理机构 ID。
• 输入字段（均为字符串）：
  • name：任务标题，例如 "Продажа {{ название товара }} на pressfinity.com"。
  • agency：代理机构/公司名称（可选）。
  • email：用于查找 Planfix 联系人的员工邮箱。
  • contactName/employeeName：员工全名（可选）。
  • telegram：员工的 Telegram 用户名（可选）。
  • description：包含所订购产品列表的描述。
  • project：与销售任务关联的项目名称（可选）。
• 返回 { taskId, url }。

planfix_create_sell_task_ids

• 已知 Planfix 标识符时创建销售任务。
• 需要数字类型的 clientId，以及可选的 leadTaskId、agencyId 和 assignees（用户 ID）。
• 接受 name、description 和可选的 project 字符串值。

5. 更新对象（PUT 请求）

   npm run planfix put task/123 --data '{"name":"Updated Task Name"}'
   

6. 删除对象

   npm run planfix delete task/123
   

在代码中使用

import { planfixClient } from './lib/planfix-client';

// Get current user
const user = await planfixClient.get('user/current');

// Create a new task
const newTask = await planfixClient.post('task/', {
  name: 'New Task',
  description: 'Task description',
  // ... other task properties
});

// Search for objects
const objects = await planfixClient.post('object/list', {
  filters: [
    {
      type: 1,
      operator: 'equal',
      value: 'Продажа'
    }
  ]
});

可用工具

线索管理

• leadToTask：通过创建/更新联系人和任务，将线索转换为任务
• searchLeadTask：根据联系信息搜索线索任务

联系人管理

• searchPlanfixContact：按姓名、电话、电子邮件或 Telegram 搜索联系人。 当主要的 email 与主电子邮件字段不匹配时，也会使用系统的次要电子邮件字段（筛选器类型 4221）进行匹配；若设置了 PLANFIX_FIELD_ID_EMAIL_ADDITIONAL，还会使用该自定义字段（筛选器类型 4101）进行匹配。对于普通的 email 搜索，这两种回退匹配都会生效——此服务会将额外电子邮件写入自定义字段，因此，要再次找到通过此服务创建的联系人，单独的 email 也必须与该字段进行匹配。可选参数 additionalEmails: string[]（最多 10 个）会将每个地址添加到上述回退匹配中，并同时匹配主电子邮件字段。
• createPlanfixContact：在 Planfix 中创建新联系人。接受可选参数 additionalEmails: string[]（最多 10 个），会将其写入额外电子邮件自定义字段（PLANFIX_FIELD_ID_EMAIL_ADDITIONAL），去重并排除主 email。（通过 API 只能读取系统的次要电子邮件字段。）
• updatePlanfixContact：更新现有联系人信息。接受可选参数 additionalEmails: string[]（最多 10 个），会将其合并到额外电子邮件自定义字段中。Planfix 自定义字段写入会替换整个值，因此该字段会重写为已有地址与真正新增地址的并集，不会丢失任何内容。联系人已有的地址——无论是在自定义字段、只读的系统次要电子邮件字段，还是作为主 email——都不会重复添加。使用 forceUpdate 时，该字段会改写为恰好包含传入的地址，因此传入空数组会清空该字段；无论如何，省略 additionalEmails 都不会改动该字段。
• searchPlanfixCompany：按名称搜索公司

任务管理

• searchPlanfixTask：按标题、客户 ID 和可选的 templateId 搜索任务
• createSellTask：解析联系人／代理机构 ID 并创建销售任务
• createSellTaskIds：已知 ID 时创建销售任务
• createLeadTask：创建新的潜在客户任务。启用 chatApi.useChatApi 时，会通过 Chat API 发送初始消息，通过 getTask 获取生成的 taskId，然后使用 REST API 更新任务。接受 message 和 contactName 字段。
• addToLeadTask：创建或更新潜在客户任务，并更新联系人详情。 接受可选参数 additionalEmails: string[]（最多 10 个），该参数会贯穿联系人搜索、创建和更新流程（匹配系统的次要电子邮件字段和 PLANFIX_FIELD_ID_EMAIL_ADDITIONAL 自定义字段；写入自定义字段）。 当 webhook.enabled 为 true 时，会将输入负载发送到 webhook 端点；如果设置了 skipPlanfixApi，则可跳过 Planfix API。
• createTask：使用文本字段创建任务
• createComment：向任务添加评论
• getChildTasks：获取父任务的子任务。使用 recursive 可 将所有后代任务作为平面列表获取；返回的任务包含 parent_task_id。
• updateLeadTask：更新现有潜在客户任务（仅更新空字段，除非 forceUpdate 为 true）

目录管理

• planfix_search_directory：按名称搜索目录
• planfix_search_directory_entry：按目录名称和条目名称搜索目录条目

用户管理

• searchManager：通过电子邮件查找经理

报告

• listReports：列出所有可用报告
• runReport：生成并获取指定报告

参考资料

• Planfix API 文档
• Model Context Protocol

待办事项：

• 添加工具 getTask，用于检索任务详情
• 添加工具 getContact，用于检索联系人详情
• 添加工具 getManager，用于检索经理详情
• 添加更全面的错误处理和日志记录
• 为所有 API 端点添加输入验证
• 为 API 调用添加速率限制和重试逻辑

---

MIT 许可证