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.
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.
- 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
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.
One command plus a key — npx @popstas/planfix-mcp-server, then supply credentials