Planfix MCP Server

MCP日程管理

提供方 popstas · 包名 @popstas/planfix-mcp-server

日程管理 stdio · 本地进程 API Key 社区 / 第三方 ClaudeCursorCodexZed
查看接入方式

Planfix MCP Server This MCP server provides integration with the Planfix API, allowing Model Context Protocol (MCP) clients to interact with Planfix CRM and task management system. Features - Lead management (create, search, convert to tasks) - Contact and company management - Task management (create, search, comment) - Report generation and management - Uses Planfix REST API v2.0 ([API docs]

一句话选型结论

按资料字段整理

Planfix MCP Server 属于日程管理类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude、Cursor、Codex 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类日程管理 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

日程管理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

mcp serverapi integration

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
npx -y @popstas/planfix-mcp-server

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 node,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
日程安排

按空闲时间自动排日程。

提醒与待办

设提醒、管待办清单。

时间协调

在多人之间找共同空档。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude、Cursor、Codex,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在日程管理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Planfix MCP Server当前 未标注 stdio · 本地进程 本地部署 有 未标注
Todoist MCP Server 79e800d2 35 stdio · 本地进程 支持远程部署 有 2026-05-17
Outlook Calendar MCP 7 stdio · 本地进程 本地部署 有 2026-05-18
MCP Server Apple Events 5 stdio · 本地进程 本地部署 有 2026-05-17
y-cli 未标注 stdio · 本地进程 本地部署 无 2026-10-05
Google Calendar 未标注 HTTP · 远程 支持远程部署 有 2026-05-17

服务器档案

日程管理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方popstas上游标注的维护方 popstas
分类日程管理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时@popstas/planfix-mcp-server · node本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

14.0 KB
来自项目仓库与上游目录的原文,未做删改

Planfix MCP Server

This MCP server provides integration with the Planfix API, allowing Model Context Protocol (MCP) clients to interact
with Planfix CRM and task management system.

Features

  • Lead management (create, search, convert to tasks)
  • Lead searches can reuse a known clientId to skip contact lookups
  • Contact and company management
  • Task management (create, search, comment)
  • Report generation and management
  • Uses Planfix REST API v2.0 (API docs)
  • Authentication via Bearer token

Configuration

The server requires the following environment variables for Planfix API access:

  • PLANFIX_ACCOUNT – Your Planfix account name (e.g., yourcompany)
  • PLANFIX_TOKEN – Planfix API token with necessary permissions
  • PLANFIX_BASE_URL – (optional) Override the REST API base URL. Defaults to https://.planfix.com/rest/. Set this for .ru and other regional installations, e.g. https://yourcompany.planfix.ru/rest/
  • PLANFIX_ACCOUNT_URL – (optional) Override the web origin used for human-facing links (task/contact/user pages). Defaults to PLANFIX_BASE_URL without the trailing /rest/
  • PLANFIX_FIELD_ID_EMAIL – Custom field ID for email
  • PLANFIX_FIELD_ID_EMAIL_ADDITIONAL – (optional, no default) Numeric custom field ID used to store additional email addresses (multi-value). Must point at a real multi-value custom field you created on your account; the system secondary-email field id 124 is not a valid write target. When unset, storing additional addresses is disabled (matching by the system field still works). The Planfix system secondary-email field (additionalEmailAddresses) is read-only over the REST API, so additional addresses are written to this custom field; matching uses both the system field (filter type 4221) and this custom field (filter type 4101), for any email search once this is set
  • PLANFIX_FIELD_ID_PHONE – Custom field ID for phone
  • PLANFIX_FIELD_ID_TELEGRAM – Set any value to use the system Telegram field
  • PLANFIX_FIELD_ID_TELEGRAM_CUSTOM – Custom field ID for Telegram when using the custom field
  • PLANFIX_FIELD_ID_CLIENT – Custom field ID for client
  • PLANFIX_FIELD_ID_MANAGER – Custom field ID for manager
  • PLANFIX_FIELD_ID_AGENCY – Custom field ID for agency
  • PLANFIX_FIELD_ID_LEAD_SOURCE – Custom field ID for lead source
  • PLANFIX_FIELD_ID_LEAD_SOURCE_VALUE – Value ID for default lead source
  • PLANFIX_FIELD_ID_PIPELINE – Custom field ID for pipeline
  • PLANFIX_FIELD_ID_TAGS – Custom field ID for task tags
  • Missing tag names will be added automatically to the directory
  • PLANFIX_FIELD_ID_LEAD_ID – Custom field ID for external lead ID
  • PLANFIX_LEAD_TEMPLATE_ID – ID of the lead task template
  • PLANFIX_TASK_TITLE_TEMPLATE – Template for the default lead task title (e.g., {name} - client's task)

config.yml

Custom fields can also be configured via config.yml. The default path is
./data/config.yml. Override it with the --config=/abs/path/config.yml CLI
flag or the PLANFIX_CONFIG environment variable. You can also specify a
different Planfix account when using a custom config:```sh
PLANFIX_CONFIG=/etc/planfix-mcp.yml PLANFIX_ACCOUNT=demo \
npx @popstas/planfix-mcp-server
``````yaml
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` routes all Planfix REST API calls (including tool requests) through
the specified HTTP proxy.

Values from `config.yml` override matching entries from the legacy environment
variables when merged by `id`. User custom fields from this list are requested
individually by the `planfix_search_manager` tool so their values are available
in responses. Managers can be searched either by `email` or by numeric `id`
through this tool, enabling lookups when only an identifier is available.

#### Chat API

To create tasks from chat messages, add a `chatApi` block to `config.yml`:```yaml
chatApi:
  useChatApi: true
  chatApiToken: &quot;&lt;token&gt;&quot;
  providerId: &quot;&lt;id&gt;&quot;
  baseUrl: &quot;https://&lt;account&gt;.planfix.com/webchat/api&quot;
  • chatApiToken – token for Planfix Chat API requests.
  • providerId – identifier of the chat provider configured in Planfix.
  • useChatApi – enable Chat API integration. When true, task creation proceeds as:
    1. A chat is created via Chat API with the initial message.
    2. getTask retrieves the new task's taskId.
    3. Subsequent updates are made through the REST API.
  • baseUrl – base URL for Chat API calls. Defaults to https://.planfix.com/webchat/api.

Webhook

To post lead task payloads to a webhook before creating or updating a task,
add a webhook block to config.yml:```yaml
webhook:
enabled: true
url: "https://example.com/hook"
token: "<token>"
skipPlanfixApi: false


- `enabled` – whether to send the lead task payload to the webhook URL.
- `url` – webhook endpoint URL.
- `token` – shared secret appended to the JSON payload as `token`.
- `skipPlanfixApi` – when `true`, the webhook response must include `taskId`, and
  the Planfix REST API call is skipped.

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

Logging

Set LOG_LEVEL=debug to enable detailed cache logs. Logs are written to data/mcp.log.

Clearing Cache

Run npm run cache-clear to remove all cached Planfix API responses stored in data/planfix-cache.sqlite3 and delete the objects cache file data/planfix-cache.yml.

Example MCP Config (NPX)```json

{
"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} - работа с клиентом"
}
}
}
}


## Usage

### Running the Server

Run the server with the required environment variables set. Example (with npx):```sh
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=&quot;{name} - работа с клиентом&quot; \
npx @popstas/planfix-mcp-server

To run the server over Server-Sent Events (SSE), use the planfix-mcp-server-sse command:```sh
PLANFIX_ACCOUNT=yourcompany \
PLANFIX_TOKEN=your-api-token \
planfix-mcp-server-sse


### Using the Planfix Client

The Planfix client provides a convenient way to interact with the Planfix API directly from the command line.

#### Prerequisites

Make sure you have the following environment variables set in your `.env` file:```
PLANFIX_ACCOUNT=your-account
PLANFIX_TOKEN=your-api-token

Basic Commands

  1. Test the connectionbash npm run planfix test

  2. Make a GET requestbash npm run planfix get user/current

  3. Make a POST request with databash npm run planfix post task/ --data &#x27;{&quot;name&quot;:&quot;Test Task&quot;,&quot;description&quot;:&quot;Test Description&quot;}&#x27;

  4. Search for objectsbash npm run planfix post object/list --data &#x27;{&quot;filters&quot;:[{&quot;type&quot;:1,&quot;operator&quot;:&quot;equal&quot;,&quot;value&quot;:&quot;Продажа&quot;}]}&#x27;

Tool Reference

planfix_create_sell_task

  • Creates a sell task using textual information about the agency and employee.
  • Resolves the client, parent lead task, assignees, and agency IDs automatically based on the provided strings.
  • Input fields (all strings):
  • name: Task title, e.g. &quot;Продажа {{ название товара }} на pressfinity.com&quot;.
  • agency: Agency/company name (optional).
  • email: Employee email used to locate the Planfix contact.
  • contactName/employeeName: Employee full name (optional).
  • telegram: Employee telegram username (optional).
  • description: Description with the list of ordered products.
  • project: Project name to associate with the sell task (optional).
  • Returns { taskId, url }.

planfix_create_sell_task_ids

  • Creates a sell task when Planfix identifiers are already known.
  • Requires numeric clientId and optional leadTaskId, agencyId, and assignees (user IDs).
  • Accepts name, description, and optional project string values.
  1. Update an object (PUT request)bash npm run planfix put task/123 --data &#x27;{&quot;name&quot;:&quot;Updated Task Name&quot;}&#x27;

  2. Delete an objectbash npm run planfix delete task/123

Using in Code```typescript

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: 'Продажа'
}
]
});
```

Available Tools

Lead Management

  • leadToTask: Convert a lead to a task by creating/updating contact and task
  • searchLeadTask: Search for lead tasks by contact information

Contact Management

  • searchPlanfixContact: Search contacts by name, phone, email, or Telegram.
    When the primary email does not match the main email field, it is also matched
    against the system secondary-email field (filter type 4221) and, when
    PLANFIX_FIELD_ID_EMAIL_ADDITIONAL is set, against that custom field (filter
    type 4101). Both fallbacks apply to a plain email search — the custom field is
    where this server writes extras, so a lone email has to be matched against it
    for a contact created here to be found again. The optional
    additionalEmails: string[] argument (max 10) adds each address to those same
    fallbacks, plus the main email field.
  • createPlanfixContact: Create a new contact in Planfix. Accepts an optional
    additionalEmails: string[] argument (max 10) that is written to the
    additional-emails custom field (PLANFIX_FIELD_ID_EMAIL_ADDITIONAL),
    deduplicated and excluding the primary email. (The system secondary-email
    field is read-only via the API.)
  • updatePlanfixContact: Update existing contact information. Accepts an optional
    additionalEmails: string[] argument (max 10) that is merged into the
    additional-emails custom field. Planfix custom-field writes replace the whole
    value, so the field is rewritten with the union of what is already stored there
    and the genuinely new addresses; nothing is lost. Addresses already on the
    contact — in the custom field, in the read-only system secondary-email field, or
    as the primary email — are not added again. With forceUpdate the field is
    instead rewritten with exactly the addresses you pass, so an empty array clears
    it; omitting additionalEmails leaves the field untouched either way.
  • searchPlanfixCompany: Search for companies by name

Task Management

  • searchPlanfixTask: Search for tasks by title, client ID and optional templateId
  • createSellTask: Resolve contact/agency IDs and create a sell task
  • createSellTaskIds: Create a sell task when IDs are already known
  • createLeadTask: Create a new lead task. When chatApi.useChatApi
    is enabled, it sends the initial message through the Chat API, gets
    the resulting taskId via getTask, and then updates the task using
    the REST API. Accepts message and contactName fields.
  • addToLeadTask: Create or update a lead task and update contact details.
    Accepts an optional additionalEmails: string[] argument (max 10) that threads through
    contact search, creation, and update (matched against the system secondary-email
    field and the PLANFIX_FIELD_ID_EMAIL_ADDITIONAL custom field; written to the
    custom field).
    When webhook.enabled is true, it posts the input payload to the
    webhook endpoint, optionally skipping the Planfix API if skipPlanfixApi
    is set.
  • createTask: Create a task using text fields
  • createComment: Add a comment to a task
  • getChildTasks: Retrieve child tasks of a parent task. Use recursive to
    fetch all descendant tasks as a flat list; returned tasks include
    parent_task_id.
  • updateLeadTask: Update an existing lead task (only empty fields are updated unless forceUpdate is true)

Directory Management

  • planfix_search_directory: Search directories by name
  • planfix_search_directory_entry: Search directory entry by directory name and entry name

User Management

  • searchManager: Find a manager by email

Reporting

  • listReports: List all available reports
  • runReport: Generate and retrieve a specific report

References

  • Planfix API Documentation
  • Model Context Protocol

TODO:

  • Add tool getTask to retrieve task details
  • Add tool getContact to retrieve contact details
  • Add tool getManager to retrieve manager details
  • Add more comprehensive error handling and logging
  • Add input validation for all API endpoints
  • Add rate limiting and retry logic for API calls

MIT License

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Planfix MCP Server 怎么安装?

在客户端按下面的安装命令接入:npx -y @popstas/planfix-mcp-server。对应的包名是 @popstas/planfix-mcp-server。装完在客户端配置里引用同一个包或端点。

Planfix MCP Server 怎么在 Claude、Cursor、Codex 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Planfix MCP Server 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Planfix MCP Server 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Planfix MCP Server 支持哪些客户端?

资料标注支持 Claude、Cursor、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Planfix MCP Server 能提供哪些能力?

资料显示能力标签包括 mcp server、api integration。具体工具清单以官方文档为准。

Planfix MCP Server 需要什么运行环境?

运行时为 node;属于本地进程,需要在本机装好运行环境。

Planfix MCP Server 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。