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:

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: ""
  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`:

chatApi:
  useChatApi: true
  chatApiToken: ""
  providerId: ""
  baseUrl: "https://.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. 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`:

webhook:
  enabled: true
  url: "https://example.com/hook"
  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)

{
  "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):

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 the `planfix-mcp-server-sse` command:

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 connection

npm run planfix test

2. Make a GET request

npm run planfix get user/current

3. Make a POST request with data

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

4. Search for objects

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

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

5. Update an object (PUT request)

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

6. Delete an object

npm run planfix delete task/123

Using in Code

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

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