An MCP server for integrating with the Planfix project management and CRM platform.
This MCP server provides integration with the Planfix API, allowing Model Context Protocol (MCP) clients to interact with Planfix CRM and task management system.
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 permissionsPLANFIX_FIELD_ID_EMAIL
– Custom field ID for emailPLANFIX_FIELD_ID_PHONE
– Custom field ID for phonePLANFIX_FIELD_ID_TELEGRAM
– Set any value to use the system Telegram fieldPLANFIX_FIELD_ID_TELEGRAM_CUSTOM
– Custom field ID for Telegram when using the custom fieldPLANFIX_FIELD_ID_CLIENT
– Custom field ID for clientPLANFIX_FIELD_ID_MANAGER
– Custom field ID for managerPLANFIX_FIELD_ID_AGENCY
– Custom field ID for agencyPLANFIX_FIELD_ID_LEAD_SOURCE
– Custom field ID for lead sourcePLANFIX_FIELD_ID_LEAD_SOURCE_VALUE
– Value ID for default lead sourcePLANFIX_FIELD_ID_PIPELINE
– Custom field ID for pipelinePLANFIX_FIELD_ID_TAGS
– Custom field ID for task tags
PLANFIX_FIELD_ID_LEAD_ID
– Custom field ID for external lead IDPLANFIX_LEAD_TEMPLATE_ID
– ID of the lead task templatePLANFIX_TASK_TITLE_TEMPLATE
– Template for the default lead task title (e.g., {name} - client's task
)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
leadTaskFields:
- id: "456"
name: "id сделки"
argName: lead_id
type: number
contactFields:
- id: "123"
name: "Резидентство"
argName: resident
type: enum
values: ["резидент", "нерезидент", "иное"]
Values from config.yml
override matching entries from the legacy environment
variables when merged by id
.
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:
getTask
retrieves the new task's taskId
.baseUrl
– base URL for Chat API calls. Defaults to https://<account>.planfix.com/webchat/api
.npx @modelcontextprotocol/inspector node d:/projects/expertizeme/planfix-mcp-server/dist/index.js
Set LOG_LEVEL=debug
to enable detailed cache logs. Logs are written to data/mcp.log
.
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
.
{
"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 the planfix-mcp-server-sse
command:
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 .env
file:
PLANFIX_ACCOUNT=your-account
PLANFIX_TOKEN=your-api-token
Test the connection
npm run planfix test
Make a GET request
npm run planfix get user/current
Make a POST request with data
npm run planfix post task/ --data '{"name":"Test Task","description":"Test Description"}'
Search for objects
npm run planfix post object/list --data '{"filters":[{"type":1,"operator":"equal","value":"Продажа"}]}'
Update an object (PUT request)
npm run planfix put task/123 --data '{"name":"Updated Task Name"}'
Delete an object
npm run planfix delete task/123
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 tasksearchLeadTask
: Search for lead tasks by contact informationsearchPlanfixContact
: Search contacts by name, phone, email, or TelegramcreatePlanfixContact
: Create a new contact in PlanfixupdatePlanfixContact
: Update existing contact informationsearchPlanfixCompany
: Search for companies by namesearchPlanfixTask
: Search for tasks by title, client ID and optional templateId
createSellTask
: Create a new sell task with templatecreateLeadTask
: 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 detailscreateTask
: Create a task using text fieldscreateComment
: Add a comment to a taskgetChildTasks
: Retrieve all child tasks of a parent taskupdateLeadTask
: Update an existing lead task (only empty fields are updated unless forceUpdate
is true)planfix_search_directory
: Search directories by nameplanfix_search_directory_entry
: Search directory entry by directory name and entry namesearchManager
: Find a manager by emaillistReports
: List all available reportsrunReport
: Generate and retrieve a specific reportgetTask
to retrieve task detailsgetContact
to retrieve contact detailsgetManager
to retrieve manager detailsMIT License
Tools for PostHog analytics, annotations, and project management.
An automated tool for searching and commenting on the social media platform Xiaohongshu (Rednote) using Playwright.
CalDAV Nectcloud calendar integration. Manage calendars, events, attendees, etc.
A server for interacting with the Hyperweb platform and its tools using AI agents.
Integrate with Smartsheet for project management and data analytics, requiring an API access token.
Interact with Outline, the open-source knowledge base and wiki, directly through your AI assistant.
Manage WordPress sites and create content with AI-generated featured images.
A spellchecker and grammar checker for developers, requiring a Hyperspell token for authentication.
Analyze and visualize data from .xlsx and .csv files using matplotlib and plotly.
Monitor team productivity, usage, and spending for AI assistants using the Cursor Admin API.