Labsco
popstas logo

Planfix

★ 9

from popstas

An MCP server for integrating with the Planfix project management and CRM platform.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#email#automation#crm#database

Planfix MCP Server

Coverage Status

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

Debug

Copy & paste — that's it
npx @modelcontextprotocol/inspector node d:/projects/expertizeme/planfix-mcp-server/dist/index.js

Logging

Set LOG_LEVEL=debug to enable detailed cache logs. Logs are written to data/mcp.log.

Clearing Cache

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.

Example MCP Config (NPX)

Copy & paste — that's it
{
  "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} - работа с клиентом"
      }
    }
  }
}

Tool Reference

planfix_create_sell_task

  • Creates a sell task using textual information about the agency and employee.
  • Resolves the client, parent lead task, assignees, and agency IDs automatically based on the provided strings.
  • Input fields (all strings):
    • name: Task title, e.g. "Продажа {{ название товара }} на pressfinity.com".
    • agency: Agency/company name (optional).
    • email: Employee email used to locate the Planfix contact.
    • contactName/employeeName: Employee full name (optional).
    • telegram: Employee telegram username (optional).
    • description: Description with the list of ordered products.
    • project: Project name to associate with the sell task (optional).
  • Returns { taskId, url }.

planfix_create_sell_task_ids

  • Creates a sell task when Planfix identifiers are already known.
  • Requires numeric clientId and optional leadTaskId, agencyId, and assignees (user IDs).
  • Accepts name, description, and optional project string values.

  1. Update an object (PUT request)

    Copy & paste — that's it
    npm run planfix put task/123 --data '{"name":"Updated Task Name"}'

  2. Delete an object

    Copy & paste — that's it
    npm run planfix delete task/123

Using in Code

Copy & paste — that's it
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: 'Продажа'
    }
  ]
});

Available Tools

Lead Management

  • leadToTask: Convert a lead to a task by creating/updating contact and task
  • searchLeadTask: Search for lead tasks by contact information

Contact Management

  • searchPlanfixContact: Search contacts by name, phone, email, or Telegram
  • createPlanfixContact: Create a new contact in Planfix
  • updatePlanfixContact: Update existing contact information
  • searchPlanfixCompany: Search for companies by name

Task Management

  • searchPlanfixTask: Search for tasks by title, client ID and optional templateId
  • createSellTask: Resolve contact/agency IDs and create a sell task
  • createSellTaskIds: Create a sell task when IDs are already known
  • createLeadTask: 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 details. When webhook.enabled is true, it posts the input payload to the webhook endpoint, optionally skipping the Planfix API if skipPlanfixApi is set.
  • createTask: Create a task using text fields
  • createComment: Add a comment to a task
  • getChildTasks: Retrieve child tasks of a parent task. Use recursive to fetch all descendant tasks as a flat list; returned tasks include parent_task_id.
  • updateLeadTask: Update an existing lead task (only empty fields are updated unless forceUpdate is true)

Directory Management

  • planfix_search_directory: Search directories by name
  • planfix_search_directory_entry: Search directory entry by directory name and entry name

User Management

  • searchManager: Find a manager by email

Reporting

  • listReports: List all available reports
  • runReport: Generate and retrieve a specific report

References

TODO:

  • Add tool getTask to retrieve task details
  • Add tool getContact to retrieve contact details
  • Add tool getManager to retrieve manager details
  • Add more comprehensive error handling and logging
  • Add input validation for all API endpoints
  • Add rate limiting and retry logic for API calls

MIT License