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.

- Lead management (create, search, convert to tasks)
- Lead searches can reuse a knownclientIdto 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

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

proxyUrlroutes all Planfix REST API calls (including tool requests) through the specified HTTP proxy.

Values fromconfig.ymloverride matching entries from the legacy environment variables when merged byid. User custom fields from this list are requested individually by theplanfix_search_managertool so their values are available in responses. Managers can be searched either byemailor by numericidthrough this tool, enabling lookups when only an identifier is available.

To create tasks from chat messages, add achatApiblock toconfig.yml:

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

- chatApiToken– token for Planfix Chat API requests.
- providerId– identifier of the chat provider configured in Planfix.
- useChatApi– enable Chat API integration. Whentrue, task creation proceeds as:
- A chat is created via Chat API with the initial message.
- getTaskretrieves the new task'staskId.
- Subsequent updates are made through the REST API.

To post lead task payloads to a webhook before creating or updating a task, add awebhookblock toconfig.yml:

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 astoken.
- skipPlanfixApi– whentrue, the webhook response must includetaskId, and the Planfix REST API call is skipped.

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

SetLOG_LEVEL=debugto enable detailed cache logs. Logs are written todata/mcp.log.

Runnpm run cache-clearto remove all cached Planfix API responses stored indata/planfix-cache.sqlite3and delete the objects cache filedata/planfix-cache.yml.

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

Run the server with the required environment variables set. Example (with 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

To run the server over Server-Sent Events (SSE), use theplanfix-mcp-server-ssecommand:

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

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

Make sure you have the following environment variables set in your.envfile:

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

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

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

- 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."Продажа {{ название товара }} на pressfinity.com".
- 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).

- Creates a sell task when Planfix identifiers are already known.
- Requires numericclientIdand optionalleadTaskId,agencyId, andassignees(user IDs).
- Acceptsname,description, and optionalprojectstring values.

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

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: Convert a lead to a task by creating/updating contact and task
- searchLeadTask: Search for lead tasks by contact information

- searchPlanfixContact: Search contacts by name, phone, email, or Telegram. When the primaryemaildoes not match the main email field, it is also matched against the system secondary-email field (filter type 4221) and, whenPLANFIX_FIELD_ID_EMAIL_ADDITIONALis set, against that custom field (filter type 4101). Both fallbacks apply to a plainemailsearch — the custom field is where this server writes extras, so a loneemailhas to be matched against it for a contact created here to be found again. The optionaladditionalEmails: 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 optionaladditionalEmails: string[]argument (max 10) that is written to the additional-emails custom field (PLANFIX_FIELD_ID_EMAIL_ADDITIONAL), deduplicated and excluding the primaryemail. (The system secondary-email field is read-only via the API.)
- updatePlanfixContact: Update existing contact information. Accepts an optionaladditionalEmails: 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 primaryemail— are not added again. WithforceUpdatethe field is instead rewritten with exactly the addresses you pass, so an empty array clears it; omittingadditionalEmailsleaves the field untouched either way.
- searchPlanfixCompany: Search for companies by name

- searchPlanfixTask: Search for tasks by title, client ID and optionaltemplateId
- 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. WhenchatApi.useChatApiis enabled, it sends the initial message through the Chat API, gets the resultingtaskIdviagetTask, and then updates the task using the REST API. AcceptsmessageandcontactNamefields.
- addToLeadTask: Create or update a lead task and update contact details. Accepts an optionaladditionalEmails: string[]argument (max 10) that threads through contact search, creation, and update (matched against the system secondary-email field and thePLANFIX_FIELD_ID_EMAIL_ADDITIONALcustom field; written to the custom field). Whenwebhook.enabledis true, it posts the input payload to the webhook endpoint, optionally skipping the Planfix API ifskipPlanfixApiis set.
- createTask: Create a task using text fields
- createComment: Add a comment to a task
- getChildTasks: Retrieve child tasks of a parent task. Userecursiveto fetch all descendant tasks as a flat list; returned tasks includeparent_task_id.
- updateLeadTask: Update an existing lead task (only empty fields are updated unlessforceUpdateis true)

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

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

- Planfix API Documentation
- Model Context Protocol

Interact with Monday.com boards, items, updates, and documents.