Planhat MCP

メモ

ホスト型コネクターの OAuth やカスタムコネクターの設定が妨げになる場合、Planhat MCP を使えば標準 API トークンで直接ローカル接続できます。ホストするものはなく、AI と顧客データの間にサードパーティのサービスが介在することもありません。

動作を確認する

あなた：「今四半期にライセンスの更新を迎える企業はどこですか？」

**Claude：**ローカル MCP サーバー経由で Planhat に問い合わせ、該当する企業と更新の詳細を返します。

Claude にレコードの一覧表示、顧客の状況の確認、フォローアップタスクの作成、会話から直接 Planhat を更新するよう依頼できます。

Claude Desktop にインストールする

ファイルを 1 つダウンロードしてダブルクリックし、トークンを貼り付けます。ターミナルも設定ファイルもコードも不要で、事前にインストールするものもありません。

1. .mcpb ファイルをダウンロードします。
2. ダウンロードしたファイルをダブルクリックします。Claude Desktop にインストール用ポップアップが表示されます。
3. ポップアップの内容を確認して、インストールをクリックします。
4. Planhat API トークンをまだお持ちでない場合は作成します。Planhat で Settings > Service Accounts (Private Apps) > API Access Token に移動してください。管理者権限が必要です。
5. トークン欄にトークンを貼り付けます。トークンはシステムのキーチェーンに保存され、ディスク上のファイルには保存されません。
6. 任意：読み取り専用モードまたは削除ツールを無効にするにチェックを入れると、AI が実行できる操作を制限できます。
7. Claude に 「Planhat の上位 3 社を一覧表示して」 と尋ねます。回答があれば完了です。

ダブルクリックしても Claude Desktop が開かない場合は、Settings > Extensions > Advanced settings > Install Extension を開き、ダウンロードしたファイルを選択してください。

各リリースには planhat-mcp.mcpb.sha256 も含まれています。macOS または Linux でダウンロードを検証するには、2 つのファイルを同じディレクトリに置いて、次を実行します。

shasum -a 256 -c planhat-mcp.mcpb.sha256

手動インストールから切り替えますか？ すべてのツールが 2 つずつ表示されないよう、先に claude_desktop_config.json から古い planhat エントリを削除してください。

手動インストール

Claude Desktop 以外の MCP クライアントを使用する場合、またはチェックアウトから実行する場合に利用します。Node.js 18 以降が必要です。

1. コードを取得してサーバーをビルドします：

git clone https://github.com/da-troll/Planhat-MCP.git ~/planhat-mcp
cd ~/planhat-mcp
npm install
npm run build

2. Planhat トークンを追加します：

cp .env.example .env
open .env        # paste your token after PLANHAT_TOKEN= and save

トークンは、ご使用のマシン上のその 1 つのファイルにのみ保存されます。パスワードと同様に取り扱ってください。

3. クライアントの MCP 設定にサーバーを登録します（Claude Desktop の場合：claude_desktop_config.json、Cursor の場合：.cursor/mcp.json）。YOUR-USERNAME を置き換えてください。

{
  "mcpServers": {
    "planhat": {
      "command": "node",
      "args": ["/Users/YOUR-USERNAME/planhat-mcp/dist/server.js"]
    }
  }
}

クライアントを再起動し、上記と同じ質問をして動作を確認してください。

Claude でできること

12 種類の Planhat リソースに対応する 60 個のツールがあります。すべてのリソースで、同じ 5 つの操作（list、get、create、update、delete）が使えます。

リソース	内容
企業	顧客アカウント
連絡先（エンドユーザー）	顧客企業の担当者
商談	営業・拡大に関する案件
メモ	アカウントに記録されたメモ
会話	メール、通話、メモ、チケットなど、記録されたすべての接点
ユーザー	Planhat の自社チームメンバー
アセット	顧客に紐づく製品・オブジェクト
課題	バグや機能リクエスト
チケット	サポートチケット
タスク	ToDo と予定されたアクティビティ
ライセンス	継続収益の記録
請求書	請求記録

Claude は、依頼されたことだけを実行します。また、作成するトークンによって、アクセス可能な対象が制御されます。読み取り専用トークンを使うと、コネクター全体が読み取り専用になります。

オプションのセキュリティ強化

次の 2 つのスイッチを設定すると、接続された AI がどのような依頼を受けても実行できる操作を制限できます。バンドルのインストールでは、インストール時のポップアップでチェックボックスとして表示されます。手動インストールでは、いずれかを .env ファイルに追加します。

設定	効果
PLANHAT_READ_ONLY=1	list/get ツールのみが利用可能になり、Planhat のデータは一切変更できません。
PLANHAT_DISABLE_DELETE=1	レコードの削除を除き、すべての操作が可能です。

各ツールには、標準の MCP アノテーション（readOnlyHint、destructiveHint）も設定されています。そのため、ツールごとに権限確認の方法を調整するクライアント（破壊的な呼び出しの前に確認し、読み取りを自動承認するクライアント）は、適切なシグナルを受け取れます。確認を求めるかどうか、またいつ求めるかは、常にクライアントの判断です。上記のスイッチと Planhat トークン自体に設定された権限（SECURITY.md を参照）が、厳格な制限となります。

リポジトリの構成

planhat-mcp/
├── README.md                  ← you are here
├── manifest.json              ← .mcpb bundle definition (one-click install)
├── package.json               ← dependencies, scripts, version
├── package-lock.json          ← pinned dependency versions
├── tsconfig.json              ← TypeScript config
├── .env.example               ← token template for manual installs
├── .mcpbignore                ← what stays out of the bundle
├── src/
│   ├── index.ts               ← entry point: load config, serve over stdio
│   ├── server.ts              ← registers tools, applies gates + annotations
│   ├── tools.ts               ← all 60 tool definitions
│   ├── http.ts                ← Planhat REST client
│   └── env.ts                 ← .env loader for manual installs
├── tests/
│   ├── tools.test.ts          ← offline tests for all 60 tools
│   └── http.test.ts           ← HTTP layer: timeout, errors, delete cases
├── AGENTS.md                  ← handbook for AI coding agents
├── CLAUDE.md → AGENTS.md      ← same file, Claude's preferred name
├── LICENSE                    ← MIT
├── CHANGELOG.md               ← release history
├── SECURITY.md                ← token handling & reporting issues
├── CONTRIBUTING.md            ← how to add tools or fix bugs
└── .github/workflows/
    ├── ci.yml                 ← typecheck + tests + bundle gate on every push
    └── release.yml            ← GitHub release with .mcpb asset on version tags

配布バンドルに含まれるファイルは 5 つのみです。manifest.json、dist/server.js（依存関係のない単一のビルド成果物）、assets/icon.png、LICENSE、README.md です。

トラブルシューティング

症状	考えられる原因と解決方法
.mcpb をダブルクリックしても何も起きない、または「インストール」がグレー表示される	Claude Desktop を最近のバージョンに更新してください。古いビルドは、ワンクリックでインストールできる .mcpb 拡張機能に対応していません。Settings > Extensions > Advanced > Install Extension からインストールすることもできます。
Planhat のツールがすべて 2 つずつ表示される	バンドルと古い手動設定の両方がインストールされています。claude_desktop_config.json から mcpServers.planhat を削除してください。
Claude に Planhat のツールがないと表示される	Claude Desktop が設定を読み込むのは起動時のみです。完全に終了してから再度開き、JSON の末尾に余分なカンマがないことを確認してください。
ツールの結果に HTTP 401 Unauthorized と表示される	トークンが間違っているか、有効期限が切れているか、ローテーションされています。新しいトークンを貼り付けてください。
PLANHAT_TOKEN is not set と表示される	バンドルをインストールした場合：拡張機能の設定を再度開き、トークンを入力してください。手動インストールの場合：サーバーの隣に .env がないため、手動インストールの手順 2 をもう一度実行してください。
command not found: node と表示される（手動インストール）	Node.js 18 以降をインストールするか、command に node バイナリのフルパスを指定してください。
ツールは動作するが、[] が返される	通常、エラーではありません。フィルター条件に一致する Planhat リソースが実際に空です。

エンジニア向け

npm install          # install dependencies
npm test             # offline test suite (never touches the live API)
npm run typecheck    # TypeScript type checking
npm run build        # produce dist/server.js
npm start            # run the built server over stdio

ワンクリックバンドルをローカルでビルドするには、npm run build && npx -y @anthropic-ai/[email protected] pack . planhat.mcpb を実行してください。

アーキテクチャに関するメモ、API の特有の動作、コントリビューションのルールは、AGENTS.md と CONTRIBUTING.md に記載されています。エンドポイントのパスは、2026 年 7 月に稼働中の Planhat API で検証済みです。特に、Planhat には /notes や /activities の REST エンドポイントがありません。メモとチケットは、内部的には /conversations を使います（詳しくは AGENTS.md を参照してください）。

ライセンス

MIT です。自由にお使いください。無保証です。