Planfix MCP Server

Planfix MCP サーバー

この MCP サーバーは Planfix API と連携し、Model Context Protocol（MCP）クライアントが Planfix CRM およびタスク管理システムを操作できるようにします。

機能

• リード管理（作成、検索、タスクへの変換）
• リード検索では、既知の clientId を再利用して連絡先の検索を省略できます
• 連絡先および会社の管理
• タスク管理（作成、検索、コメント）
• レポートの生成と管理
• Planfix REST API v2.0 を使用します（API ドキュメント）
• Bearer トークンによる認証

設定

Planfix API にアクセスするには、次の環境変数が必要です。

• PLANFIX_ACCOUNT – Planfix アカウント名（例：yourcompany）
• PLANFIX_TOKEN – 必要な権限を持つ Planfix API トークン
• PLANFIX_BASE_URL – （任意）REST API のベース URL を上書きします。デフォルトは https://<PLANFIX_ACCOUNT>.planfix.com/rest/ です。.ru などの地域別インストール環境では、https://yourcompany.planfix.ru/rest/ のように設定します
• PLANFIX_ACCOUNT_URL – （任意）ユーザー向けリンク（タスク／連絡先／ユーザーのページ）で使用するウェブのオリジンを上書きします。デフォルトは、末尾の /rest/ を除いた PLANFIX_BASE_URL です
• PLANFIX_FIELD_ID_EMAIL – メールアドレス用カスタムフィールド ID
• PLANFIX_FIELD_ID_EMAIL_ADDITIONAL – （任意、デフォルト値なし）追加のメールアドレス（複数値）を保存するための数値のカスタムフィールド ID です。アカウントで作成した実際の複数値カスタムフィールドを指定する必要があります。システムのセカンダリメールフィールド ID 124 は書き込み先として使用できません。未設定の場合、追加アドレスの保存は無効になります（システムフィールドによる照合は引き続き機能します）。Planfix のシステムのセカンダリメールフィールド（additionalEmailAddresses）は REST API 経由で読み取り専用のため、追加アドレスはこのカスタムフィールドに書き込まれます。この設定を有効にすると、メール検索ではシステムフィールド（フィルタータイプ 4221）とこのカスタムフィールド（フィルタータイプ 4101）の両方を使って照合します
• PLANFIX_FIELD_ID_PHONE – 電話番号用カスタムフィールド ID
• PLANFIX_FIELD_ID_TELEGRAM – システムの Telegram フィールドを使用するには、任意の値を設定します
• PLANFIX_FIELD_ID_TELEGRAM_CUSTOM – カスタムフィールドを使用する場合の Telegram 用カスタムフィールド ID
• PLANFIX_FIELD_ID_CLIENT – クライアント用カスタムフィールド ID
• PLANFIX_FIELD_ID_MANAGER – マネージャー用カスタムフィールド ID
• PLANFIX_FIELD_ID_AGENCY – 代理店用カスタムフィールド ID
• PLANFIX_FIELD_ID_LEAD_SOURCE – リードソース用カスタムフィールド ID
• PLANFIX_FIELD_ID_LEAD_SOURCE_VALUE – デフォルトのリードソースの値 ID
• PLANFIX_FIELD_ID_PIPELINE – パイプライン用カスタムフィールド ID
• PLANFIX_FIELD_ID_TAGS – タスクタグ用カスタムフィールド ID
  • 存在しないタグ名はディレクトリに自動的に追加されます
• PLANFIX_FIELD_ID_LEAD_ID – 外部リード ID 用カスタムフィールド ID
• PLANFIX_LEAD_TEMPLATE_ID – リードタスクテンプレートの ID
• PLANFIX_TASK_TITLE_TEMPLATE – デフォルトのリードタスクタイトルのテンプレート（例：{name} - client's task）

config.yml

カスタムフィールドは config.yml でも設定できます。デフォルトのパスは ./data/config.yml です。--config=/abs/path/config.yml CLI フラグまたは PLANFIX_CONFIG 環境変数でパスを上書きできます。カスタム設定を使用する際は、別の Planfix アカウントを指定することもできます。

PLANFIX_CONFIG=/etc/planfix-mcp.yml PLANFIX_ACCOUNT=demo \
npx @popstas/planfix-mcp-server

proxyUrl: "http://localhost:8080"

webhook:
  enabled: false
  url: "https://example.com/hook"
  token: "<token>"
  skipPlanfixApi: false

leadTaskFields:
  - id: "456"
    name: "id сделки"
    argName: lead_id
    type: number
contactFields:
  - id: "123"
    name: "Резидентство"
    argName: resident
    type: enum
    values: ["резидент", "нерезидент", "иное"]
userFields:
  - id: "789"
    name: "Департамент"
    argName: department
    type: string

proxyUrl を設定すると、すべての Planfix REST API 呼び出し（ツールリクエストを含む）が指定した HTTP プロキシ経由でルーティングされます。

config.yml の値は、id によって統合される際に、対応する従来の環境変数の値を上書きします。このリストにあるユーザー定義のカスタムフィールドは、値をレスポンスで利用できるようにするため、planfix_search_manager ツールによって個別にリクエストされます。このツールでは、email または数値の id でマネージャーを検索できるため、識別子しか分からない場合でも検索できます。

チャット API

チャットメッセージからタスクを作成するには、config.yml に chatApi ブロックを追加します。

chatApi:
  useChatApi: true
  chatApiToken: "<token>"
  providerId: "<id>"
  baseUrl: "https://<account>.planfix.com/webchat/api"

• chatApiToken – Planfix Chat API リクエスト用のトークンです。
• providerId – Planfix で設定したチャットプロバイダーの識別子です。
• useChatApi – Chat API との連携を有効にします。true の場合、タスクは次の手順で作成されます。
  1. 最初のメッセージとともに、Chat API 経由でチャットが作成されます。
  2. getTask で新しいタスクの taskId を取得します。
  3. 以降の更新は REST API 経由で行われます。
• baseUrl – Chat API 呼び出しのベース URL です。デフォルトは https://<account>.planfix.com/webchat/api です。

Webhook

タスクの作成または更新前に、リードタスクのペイロードを Webhook に送信するには、 config.yml に webhook ブロックを追加します。

webhook:
  enabled: true
  url: "https://example.com/hook"
  token: "<token>"
  skipPlanfixApi: false

• enabled – リードタスクのペイロードを Webhook URL に送信するかどうかを指定します。
• url – Webhook エンドポイントの URL です。
• token – JSON ペイロードに token として追加される共有シークレットです。
• skipPlanfixApi – true の場合、Webhook の応答に taskId を含める必要があり、 Planfix REST API の呼び出しはスキップされます。

デバッグ

npx @modelcontextprotocol/inspector node d:/projects/expertizeme/planfix-mcp-server/dist/index.js

ログ

LOG_LEVEL=debug を設定すると、詳細なキャッシュログが有効になります。ログは data/mcp.log に書き込まれます。

キャッシュのクリア

npm run cache-clear を実行すると、data/planfix-cache.sqlite3 に保存されている Planfix API のすべてのキャッシュ済みレスポンスが削除され、オブジェクトキャッシュファイル data/planfix-cache.yml も削除されます。

MCP 設定例（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} - работа с клиентом"
      }
    }
  }
}

使用方法

サーバーの実行

必要な環境変数を設定してサーバーを実行します。例（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

Server-Sent Events（SSE）経由でサーバーを実行するには、planfix-mcp-server-sse コマンドを使用します。

PLANFIX_ACCOUNT=yourcompany \
PLANFIX_TOKEN=your-api-token \
planfix-mcp-server-sse

Planfix クライアントの使用

Planfix クライアントを使用すると、コマンドラインから Planfix API を直接、簡単に操作できます。

前提条件

.env ファイルに次の環境変数が設定されていることを確認してください。

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

基本コマンド

1. 接続をテストする

   npm run planfix test
   

2. GET リクエストを送信する

   npm run planfix get user/current
   

3. データを含む POST リクエストを送信する

   npm run planfix post task/ --data '{"name":"Test Task","description":"Test Description"}'
   

4. オブジェクトを検索する

   npm run planfix post object/list --data '{"filters":[{"type":1,"operator":"equal","value":"Продажа"}]}'
   

ツールリファレンス

planfix_create_sell_task

• 代理店と従業員に関するテキスト情報を使用して、販売タスクを作成します。
• 指定された文字列に基づいて、クライアント、親リードタスク、担当者、代理店の ID を自動的に特定します。
• 入力フィールド（すべて文字列）：
  • name：タスクのタイトル。例："Продажа {{ название товара }} на pressfinity.com"。
  • agency：代理店／会社名（任意）。
  • email：Planfix の連絡先を特定するために使用する従業員のメールアドレスです。
  • contactName/employeeName：従業員の氏名（任意）。
  • telegram：従業員の Telegram ユーザー名（任意）。
  • description：注文された商品一覧を含む説明です。
  • project：販売タスクに関連付けるプロジェクト名（任意）。
• { taskId, url } を返します。

planfix_create_sell_task_ids

• Planfix の識別子が既知の場合に、販売タスクを作成します。
• 数値の clientId と、任意で leadTaskId、agencyId、assignees（ユーザー ID）が必要です。
• name、description、および任意の project の文字列値を受け取ります。

5. オブジェクトを更新する（PUT リクエスト）

   npm run planfix put task/123 --data '{"name":"Updated Task Name"}'
   

6. オブジェクトを削除する

   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：連絡先とタスクを作成／更新して、リードをタスクに変換します。
• searchLeadTask：連絡先情報を使用してリードタスクを検索します

連絡先管理

• searchPlanfixContact：名前、電話番号、メールアドレス、Telegram で連絡先を検索します。 主メールアドレスの email がメインのメールアドレス欄と一致しない場合、システムのセカンダリメールアドレス欄（フィルタータイプ 4221）とも照合します。また、PLANFIX_FIELD_ID_EMAIL_ADDITIONAL が設定されている場合は、そのカスタムフィールド（フィルタータイプ 4101）とも照合します。どちらの代替照合も通常の email 検索に適用されます。このサーバーは追加のメールアドレスをカスタムフィールドに書き込むため、このサーバーで作成した連絡先を再度見つけるには、単独の email もそのフィールドと照合する必要があります。省略可能な additionalEmails: string[] 引数（最大 10 件）を指定すると、各アドレスが同じ代替照合に加えて、メインのメールアドレス欄とも照合されます。
• createPlanfixContact：Planfix に新しい連絡先を作成します。省略可能な additionalEmails: string[] 引数（最大 10 件）を指定すると、アドレスが重複を除去され、主メールアドレスの email を除外したうえで、追加メールアドレスのカスタムフィールド（PLANFIX_FIELD_ID_EMAIL_ADDITIONAL）に書き込まれます。（システムのセカンダリメールアドレス欄は API 経由では読み取り専用です。）
• updatePlanfixContact：既存の連絡先情報を更新します。省略可能な additionalEmails: string[] 引数（最大 10 件）を指定すると、アドレスが追加メールアドレスのカスタムフィールドにマージされます。Planfix のカスタムフィールドへの書き込みでは値全体が置き換えられるため、すでに保存されているアドレスと新たに追加するアドレスを結合してフィールドを書き換え、既存の情報が失われないようにします。連絡先にすでに登録されているアドレス（カスタムフィールド、読み取り専用のシステムセカンダリメールアドレス欄、または主メールアドレスの email に登録済みのアドレス）は再追加されません。forceUpdate を指定すると、渡したアドレスだけでフィールドを書き換えるため、空の配列を指定するとフィールドがクリアされます。additionalEmails を省略した場合は、どちらの場合もフィールドは変更されません。
• searchPlanfixCompany：名前で会社を検索します

タスク管理

• searchPlanfixTask：タイトル、クライアント ID、および省略可能な templateId でタスクを検索します
• createSellTask：連絡先 ID と代理店 ID を解決し、販売タスクを作成します
• createSellTaskIds：ID がすでにわかっている場合に販売タスクを作成します
• createLeadTask：新しいリードタスクを作成します。chatApi.useChatApi が有効な場合、Chat API を通じて最初のメッセージを送信し、getTask で 結果の taskId を取得してから、REST API を使ってタスクを更新します。 message と contactName フィールドを受け付けます。
• addToLeadTask：リードタスクを作成または更新し、連絡先の詳細も更新します。 省略可能な additionalEmails: string[] 引数（最大 10 件）を指定すると、連絡先の検索、 作成、更新に引き継がれます（システムのセカンダリメールアドレス欄および PLANFIX_FIELD_ID_EMAIL_ADDITIONAL カスタムフィールドと照合され、カスタムフィールドに 書き込まれます）。 webhook.enabled が true の場合、入力ペイロードを webhook エンドポイントに送信します。skipPlanfixApi が設定されている場合は、 Planfix API の呼び出しを省略できます。
• createTask：テキストフィールドを使ってタスクを作成します
• createComment：タスクにコメントを追加します
• getChildTasks：親タスクの子タスクを取得します。recursive を指定すると、 すべての子孫タスクをフラットなリストとして取得できます。返されるタスクには parent_task_id が含まれます。
• updateLeadTask：既存のリードタスクを更新します（forceUpdate が true でない限り、空のフィールドのみ更新します）

ディレクトリ管理

• planfix_search_directory：名前でディレクトリを検索します
• planfix_search_directory_entry：ディレクトリ名とエントリー名でディレクトリエントリーを検索します

ユーザー管理

• searchManager：メールアドレスでマネージャーを検索します

レポート

• listReports：利用可能なすべてのレポートを一覧表示します
• runReport：特定のレポートを生成して取得します

参考資料

• Planfix API ドキュメント
• Model Context Protocol

TODO:

• タスクの詳細を取得するツール getTask を追加
• 連絡先の詳細を取得するツール getContact を追加
• マネージャーの詳細を取得するツール getManager を追加
• より包括的なエラー処理とロギングを追加
• すべての API エンドポイントに入力検証を追加
• API 呼び出しにレート制限と再試行ロジックを追加

---

MIT License