Planfix MCP Server

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)
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

Configuration

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 permissions
PLANFIX_FIELD_ID_EMAIL – Custom field ID for email
PLANFIX_FIELD_ID_PHONE – Custom field ID for phone
PLANFIX_FIELD_ID_TELEGRAM – Set any value to use the system Telegram field
PLANFIX_FIELD_ID_TELEGRAM_CUSTOM – Custom field ID for Telegram when using the custom field
PLANFIX_FIELD_ID_CLIENT – Custom field ID for client
PLANFIX_FIELD_ID_MANAGER – Custom field ID for manager
PLANFIX_FIELD_ID_AGENCY – Custom field ID for agency
PLANFIX_FIELD_ID_LEAD_SOURCE – Custom field ID for lead source
PLANFIX_FIELD_ID_LEAD_SOURCE_VALUE – Value ID for default lead source
PLANFIX_FIELD_ID_PIPELINE – Custom field ID for pipeline
PLANFIX_FIELD_ID_TAGS – Custom field ID for task tags
- Missing tag names will be added automatically to the directory
PLANFIX_FIELD_ID_LEAD_ID – Custom field ID for external lead ID
PLANFIX_LEAD_TEMPLATE_ID – ID of the lead task template
PLANFIX_TASK_TITLE_TEMPLATE – Template for the default lead task title (e.g., {name} - client's task)

config.yml

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.

Debug

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)

{
  "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} - работа с клиентом"
      }
    }
  }
}

Usage

Running the Server

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

Using the Planfix Client

The Planfix client provides a convenient way to interact with the Planfix API directly from the command line.

Prerequisites

Make sure you have the following environment variables set in your .env file:

PLANFIX_ACCOUNT=your-account
PLANFIX_TOKEN=your-api-token

Basic Commands

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
```

Using in Code

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: Create a new sell task with template
createLeadTask: Create a new lead task
addToLeadTask: Create or update a lead task and update contact details
createTask: Create a task using text fields
createComment: Add a comment to a task
getChildTasks: Retrieve all child tasks of a parent task
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

Server	Summary	Actions
Resource Hub	An MCP server that connects to the Resource Hub - a central place to configure and manage your MCP s...	View
MCP Orchestrator	No documentation available.	View
macOS Notification MCP	A Model Context Protocol (MCP) server that enables AI assistants to trigger macOS notifications, sou...	View
Wiki.js	Connect Claude to your Wiki.js documentation!	View
laundry-timer-mcp	This project implements an MCP (Model Context Protocol) server designed to help with laundry plannin...	View
SPAIK AI ROI		View

Planfix