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_FIELD_ID_EMAIL – Custom field ID for email
• 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: "<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: "<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. 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 fo

... View full README on GitHub