planfix_add_to_lead_task
Create or update Planfix contact, task, and comment for a lead.
LABSCO SUMMARY
Planfix's custom-field model handled up front, so the tools speak in your account's terms rather than in field numbers.
The difficulty in a Planfix integration is not the API, it is that nearly everything meaningful lives in a custom field whose ID differs from account to account. Mapping that once — including extra lead, contact and user fields with their own argument names and enum values — is what lets an agent create a lead with a pipeline and tags instead of assembling a numbered payload. Contact search accepting a name in both Russian and English is a small detail that matters constantly in practice, and planfix_request is the escape hatch for whatever is not modelled.
What it is
A server over the Planfix REST API covering the CRM workflow: find or create a contact, open a lead task, convert it into a sell task, comment on it, walk its child tasks, and run the reports the account already defines. Because Planfix keeps most meaning in custom fields, the setup is largely telling it which field IDs mean what.
What you get
- planfix_add_to_lead_task is the one-call path for an incoming lead: the contact, the task and a comment created or updated together in a single request
- Contacts and companies searched by name, phone, email, Telegram or Instagram — with the name accepted in both Russian and English — then created or updated, and additional email addresses matched against both the system field and the custom one you nominate
- Tasks created from textual parameters or from numeric identifiers, searched by title or client ID, updated, and walked downward through planfix_get_child_tasks, recursively when you ask
- planfix_create_sell_task and its identifier-based twin turn a lead into a sale, carrying agency, client, project and assignees
- planfix_create_comment posts to a task with named recipients and a silent option when it should not notify
- Directory lookups: find a directory by name and resolve an entry inside it to its id, which is what every enum-valued custom field needs before a write
- planfix_search_manager finds a manager by email or numeric id and returns the user custom fields listed in your configuration
- planfix_reports_list, planfix_get_report_fields and planfix_run_report cover the reports the account already has, with grouping, period and sort
- planfix_request makes an arbitrary call against the Planfix REST API for anything the typed tools do not model, with a cache time
Requirements
Published as @popstas/planfix-mcp-server and launched over stdio, with an SSE binary alongside. PLANFIX_ACCOUNT and PLANFIX_TOKEN authenticate against Planfix REST API v2.0 as a Bearer token, and PLANFIX_BASE_URL overrides the endpoint for .ru and other regional installations. Most of the remaining configuration is field mapping — the custom field IDs for email, phone, Telegram, client, manager, agency, lead source, pipeline, tags and external lead ID, plus the lead task template. Those live in environment variables or in a config.yml, where entries matching by id take precedence and extra lead, contact and user fields can be declared with their own argument names and enum values.
Setup effort
One command plus a key — npx @popstas/planfix-mcp-server, then supply credentials
USE CASES
01
Turning an incoming enquiry into a lead
One call creates or updates the contact, opens the lead task with its pipeline and tags, and leaves the enquiry as a comment.
02
Checking whether you already know someone
Search contacts by phone, email or Telegram — and by name in either language — then check the company alongside them.
03
Converting a lead into a sale
Find the lead task, then create the sell task against the right agency, client and project with assignees attached.
04
Leaving an update where the team will see it
A comment on the task, addressed to specific recipients, or silent when it should not notify anyone.
05
Reading what the account already reports on
List the reports, inspect one's fields, then run it with the grouping and period you want rather than rebuilding it by hand.
06
Reaching an endpoint the typed tools do not cover
planfix_request calls the REST API directly with a method, path and body, with a cache time to avoid repeating it.
22 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
planfix_create_comment
Create a comment for a task in Planfix
planfix_create_contact
Create a new contact in Planfix
planfix_create_lead_task
Create a new lead task in Planfix
planfix_create_sell_task
Create a sell task in Planfix using textual data for agency and contact
planfix_create_sell_task_ids
Create a sell task in Planfix using numeric identifiers
planfix_create_task
Create a task using textual parameters
planfix_get_child_tasks
Get all child tasks of a specific parent task in Planfix
planfix_get_report_fields
Get fields of a specific report in Planfix
planfix_reports_list
List all available reports in Planfix with their IDs and names
planfix_request
Make a generic request to the Planfix API with the specified method, path, and body. Use when swagger.json was read.
planfix_run_report
Run a Planfix report by ID and return the report data.
planfix_search_company
Search for a company in Planfix by name
planfix_search_contact
Search for a contact in Planfix by name, phone, email, or telegram. Use name in 2 languages: Russian and English.
planfix_search_directory
Search for a Planfix directory by name
planfix_search_directory_entry
Search for directory entry id by directory name and entry name
planfix_search_lead_task
Search Planfix task by user data. Use name in 2 languages: Russian and English.
planfix_search_manager
Search for a manager in Planfix by email or id
planfix_search_project
Search for a project in Planfix by name
planfix_search_task
Search for a task in Planfix by title or client ID
planfix_update_contact
Update a contact in Planfix with new data
planfix_update_lead_task
Update a lead task in Planfix
BEFORE YOU INSTALL
What to know first
Tools you get
22 tools when we connected. The documentation uses internal camelCase names such as leadToTask while the server registers snake_case names. planfix_request, planfix_search_project and planfix_get_report_fields are undocumented.
Requires
- npx on PATH
- PLANFIX_ACCOUNT in your environment
- PLANFIX_TOKEN in your environment
CONTEXT COST
Light Standing cost
Rated by the size of the 22 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Add the block to your client, or run the command directly.
Server setup
Configuration file
JSON
{
"mcpServers": {
"planfix": {
"command": "npx",
"args": [
"-y",
"@popstas/planfix-mcp-server"
],
"env": {
"PLANFIX_ACCOUNT": "<YOUR_PLANFIX_ACCOUNT>",
"PLANFIX_TOKEN": "<YOUR_PLANFIX_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} - работа с клиентом"
}
}
}
}npx
TERMINAL
npx @popstas/planfix-mcp-server
