planfix

This MCP server provides integration with the Planfix API, enabling MCP clients to interact with Planfix CRM and task management functions such as lead management, contact and company handling, task creation and searching, as well as report generation. It authenticates using a Bearer token and relies on a set of Planfix custom fields configured via environment variables to map your Planfix data model. You can run the server with npx using the example configuration, and you can also customize behavior through a config.yml by setting proxyUrl, webhook, chatApi and various lead/task field mappings. The included tool reference describes commands like planfix_create_sell_task which creates tasks using contextual information such as agency and employee details, resolves clients and leads automatically, and assigns IDs based on supplied strings.

To operate, start the MCP server with the required environment variables in place. The server exposes MCP endpoints to clients that will leverage Planfix REST API v2.0 for operations like creating leads, tasks, and chatting via Planfix Chat API if enabled. You can also run an SSE variant of the server for event-driven updates using planfix-mcp-server-sse. The Planfix client commands in the documentation demonstrate how to test connections, perform GET/POST requests, and search objects directly from the CLI, which can be useful during development and debugging.

Prerequisites:

• Node.js installed (npm available)
• Access to Planfix account with API token

1. Install prerequisites (Node environment):

• Ensure you have Node.js and npm installed on your system.

2. Install and run the MCP server via NPX:

• Set required PLANFIX_* environment variables, for example: 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} - работа с клиентом"
• Then run: npx -y @popstas/planfix-mcp-server

3. Alternative: use the SSE variant if you prefer Server-Sent Events:

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

4. Optional: configure a custom config.yml and/or proxy settings as described in the README, using PLANFIX_CONFIG to point to a config file and PLANFIX_CONFIG overrides.

Tip: Use the provided config.yml example to map custom Planfix fields and enable features like chatApi and webhook. If you enable webhook, you can control whether the Planfix API call is skipped or included based on the webhook response. Ensure all PLANFIX_FIELD_ID_* values match your Planfix instance to avoid missing field mappings. When debugging, set LOG_LEVEL=debug to gain deeper insight into cache and API interactions. The cache directory is data/ and can be cleared with npm run cache-clear as described in the README.