Front MCP

Front MCP

ローカルの stdio サーバーに対応した MCP クライアントから Front を利用できます。会話の検索、連絡先の管理、メッセージの送信、タグ付け、割り当て、受信トレイのワークフローの自動化ができます。26 個のツールで 172 個のアクションを実行できます。

クイックスタート

1. Settings > Developers > API tokens から Front API トークンを取得します。

2. 既存の設定やサーバーを維持したまま、このサーバーを Claude Code のユーザー設定（~/.claude.json）の最上位にある mcpServers オブジェクトに追加します。プロジェクトで共有する設定には、代わりに .mcp.json を使用してください。Claude Code の MCP 設定ガイドを参照してください。

{
  "mcpServers": {
    "front": {
      "command": "npx",
      "args": ["-y", "@houst-com/front-mcp"],
      "env": {
        "FRONT_API_TOKEN": "your-front-api-token"
      }
    }
  }
}

3. Claude Code を起動します。Front ツールが利用可能になります。

Node.js 20 以降が必要です。サーバーはお客様自身の Front 認証情報を使用してローカルで実行されるため、Houst がホストするサービスは不要です。API トークンをバージョン管理に含めないでください。共有する .mcp.json ファイルでは "FRONT_API_TOKEN": "${FRONT_API_TOKEN}" を使用し、Claude Code を起動する環境でその変数を設定してください。

ワークフローの例

会話を検索する：

「請求に関する問題について Front の会話を検索して」

スレッドを確認する：

「会話 cnv_abc123 のメッセージを取得して」

連絡先を管理する：

「連絡先の一覧を表示して、メールアドレス [email protected] の人を見つけて」

タグ付けして割り当てる：

「会話 cnv_abc123 に 'urgent' のタグを付けて、チームメイト tea_xyz に割り当てて」

返信の下書きを作成する：

「会話 cnv_abc123 への返信の下書きを作成して、明日折り返すと伝えて」

OAuth の設定（推奨）

OAuth を使用すると、API トークンよりもトークンの自動更新が可能になり、セキュリティも向上します。

1. Settings > Developers > OAuth apps で Front アプリを作成します。
2. リダイレクト URI に https://localhost:9876/callback を設定します。
3. MCP サーバーが必要とするリソース権限（Read、Write、Delete、Send）を有効にします。
4. アプリを保存し、OAuth 機能の Client ID をコピーします（Settings にある App secret ではありません）。
5. ~/.front-mcp/config.json を作成します。

{
  "auth": {
    "method": "oauth",
    "oauth": {
      "client_id": "your-client-id",
      "client_secret_env": "FRONT_MCP_OAUTH_SECRET",
      "redirect_port": 9876,
      "scopes": []
    }
  }
}

6. Claude Code を設定します。

{
  "mcpServers": {
    "front": {
      "command": "npx",
      "args": ["-y", "@houst-com/front-mcp"],
      "env": {
        "FRONT_MCP_AUTH_METHOD": "oauth",
        "FRONT_MCP_OAUTH_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

7. npx @houst-com/front-mcp auth を実行して認証します（ブラウザーが開きます）。
8. トークンは暗号化され、ローカルに保存されます（AES-256-GCM、権限 0600）。

認証 CLI

front-mcp auth            # Start OAuth flow
front-mcp auth --status   # Check auth state (no token values shown)
front-mcp auth --clear    # Remove stored tokens
front-mcp --version       # Show version
front-mcp --help          # Show usage

Front の権限

MCP サーバーには、使用するアクションに対応する Front API の権限が必要です。

権限	必要な操作
Read	すべての一覧表示／取得／検索アクション
Write	作成、更新、割り当て、追加、統合、返信
Delete	削除アクション
Send	messages.create、messages.reply

OAuth の場合は、Front アプリの Features > OAuth > Resource permissions でこれらを設定します。 API トークンの場合は、トークンの作成時に権限を設定します。

ツールリファレンス

ツール	アクション
accounts	list、get、create、update、delete、list_contacts、add_contact、remove_contact
analytics	create_export、get_export、create_report、get_report
channels	list、get、update、validate、create、list_for_teammate、list_for_team
comments	list、get、create、update、list_mentions、reply
contact_groups	list、create、delete、list_contacts、add_contacts、remove_contacts
contact_lists	list、create、delete、list_contacts、add_contacts、remove_contacts
contact_notes	list、create
contacts	list、get、create、update、delete、merge、list_conversations、add_handle、remove_handle
conversations	list、get、search、create、update、delete、assign、list_events、list_followers、add_followers、remove_followers、list_inboxes、add_link、remove_links、list_messages、update_reminders、add_tag、remove_tag
custom_fields	list_for_accounts、list_for_contacts、list_for_conversations、list_for_inboxes、list_for_links、list_for_teammates
drafts	list、create、create_reply、update、delete
events	list、get
inboxes	list、get、create、list_channels、list_conversations、list_access、grant_access、revoke_access
knowledge_bases	list、get、create、update、list_categories、list_articles、get_article、create_article、update_article、delete_article、get_category、create_category、update_category、delete_category
links	list、get、create、update、list_conversations
message_template_folders	list、get、create、update、delete、list_children、create_child
message_templates	list、get、create、update、delete
messages	get、create、reply、import、receive_custom、get_seen_status、mark_seen
rules	list、get、list_for_teammate、list_for_team
shifts	list、get、create、update、list_teammates、add_teammates、remove_teammates
signatures	list、get、update、delete、create_for_teammate、create_for_team
tags	list、get、create、update、delete、list_children、create_child、list_conversations
teammate_groups	list、get、create、update、delete、list_inboxes、add_inboxes、remove_inboxes、list_teammates、add_teammates、remove_teammates、list_teams、add_teams、remove_teams
teammates	list、get、update、list_conversations、list_inboxes
teams	list、get、add_teammates、remove_teammates
token_identity	get

各アクションのポリシー階層を含む完全なリファレンスについては、docs/TOOL_REFERENCE.md を参照してください。

ポリシーエンジン

すべてのアクションは階層に分類され、デフォルトの判定が適用されます。

階層	デフォルト	例
read	許可	list、get、search
write	確認	create、update、assign
destructive	拒否	delete、remove

書き込みアクションには2段階の確認が必要です。最初の呼び出しではプロンプトが返され、2回目の呼び出しで confirm: true を指定すると実行されます。破壊的なアクションはデフォルトで拒否されます。

カスタムポリシー

~/.front-mcp/policy.json を作成します。

{
  "defaults": {
    "read": "allow",
    "write": "allow",
    "destructive": "confirm"
  },
  "overrides": [
    { "tool": "conversations", "action": "delete", "decision": "deny" },
    { "tool": "tags", "action": "*", "decision": "allow" }
  ]
}

上書きの優先順位：個別アクション > ツールのワイルドカード > 階層のデフォルト。

セキュリティモデル

• HTTPS を強制 — HTTP へのフォールバックは一切ありません
• トークンの暗号化 — PBKDF2 による鍵導出を使用した AES-256-GCM
• ファイルのアクセス権限 — トークンファイルは 0600（所有者のみ読み書き可能）
• 出力のサニタイズ — LLM がデータを参照する前に、設定可能なフィールドのマスキングを実施
• ログのマスキング — すべてのログ出力から機密フィールドをマスキング
• ポリシーエンジン — 破壊的なアクションはデフォルトで拒否し、書き込みアクションには確認が必要
• 標準出力にシークレットを出力しない — 標準出力は MCP プロトコル専用です
• 依存関係を最小限に — ネイティブの fetch、Node.js の crypto、バージョンを厳密に固定

環境変数

変数	必須	説明
FRONT_API_TOKEN	はい（OAuth を使用しない場合）	Front API トークン
FRONT_MCP_AUTH_METHOD	いいえ	oauth または api_token（デフォルト：api_token）
FRONT_MCP_OAUTH_SECRET	はい（OAuth を使用する場合）	OAuth クライアントシークレット
FRONT_MCP_LOG_LEVEL	いいえ	error、warn、info、debug（デフォルト：info）
FRONT_MCP_POLICY_FILE	いいえ	カスタムポリシー JSON ファイルへのパス

制限事項

• stdio トランスポートのみ — v1 では HTTP/SSE トランスポートはありません（将来対応予定）
• Front アカウントは 1 つのみ — サーバーインスタンスごとに 1 アカウント
• Webhook は非対応 — アウトバウンド API 呼び出しのみで、インバウンドイベント処理には対応していません
• キャッシュなし — すべてのリクエストで Front API にアクセスします（Front の最新データに依存します）
• 添付ファイル — v1 ではファイルのアップロード／ダウンロードに対応していません
• アプリケーションチャネル — チャネル固有のメッセージ同期エンドポイントには対応していません

開発

git clone https://github.com/wearehoust/front-mcp.git
cd front-mcp
npm install
npm test          # 519 tests
npm run lint      # ESLint strict
npm run type-check # TypeScript strict
npm run build     # Compile to dist/

テスト

npm test              # Unit + integration tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run smoke         # Smoke test (builds, starts, verifies 26 tools)

このプロジェクトには、519 件の単体／統合テストと、172 個のアクションを含むライブ API テストスクリプト（scripts/live-test-full.js）があります。

リリース手順

1. npm version X.Y.Z --no-git-tag-version を実行して package.json と package-lock.json を更新します。server.json の両方のバージョンフィールド、src/server.ts のサーバーバージョン、CHANGELOG.md も更新します。
2. npm の信頼済みパブリッシングが wearehoust/front-mcp と release.yml ワークフローに設定されていることを確認します。リリースワークフローでは、npm と MCP Registry に GitHub OIDC を使用します。
3. npm ci、lint、型チェック、テスト、ビルド、スモークテストを実行します。パッケージ化された npm アーティファクトと、その MCP ハンドシェイクのバージョンを確認します。
4. chore: release vX.Y.Z としてコミットし、PR を作成して、CI とレビューに合格した後にマージします。
5. main を取得し、検証済みのリリースコミットに注釈付きの vX.Y.Z タグを作成します。そのタグのみを git push origin refs/tags/vX.Y.Z でプッシュします。
6. GitHub Actions がバージョンメタデータを検証し、チェックを実行して npm パッケージを公開した後、別のジョブで server.json を MCP Registry に公開します。Registry が新しい npm バージョンをまだ認識できない場合、登録処理は短時間再試行されます。
7. 両方の Registry に新しいバージョンが反映されたことを確認し、公開された npm パッケージのスモークテストを実行します。

npm の公開には成功したものの Registry への登録に失敗した場合は、Re-run failed jobs を使用して Registry ジョブのみを再試行します。古いリリースを復旧する場合（単一の公開ジョブを使用していたワークフローを含む）は、main の Actions → Release → Run workflow を開き、v1.1.1 など既存のタグを入力します。この手動操作では、タグ付けされた server.json の登録のみを行い、npm の再公開やタグの変更は行いません。復旧ワークフローは、事前に main にマージしておく必要があります。

セキュリティ

脆弱性の報告については、SECURITY.md を参照してください。

貢献

環境構築、コード規約、PR の手順については、CONTRIBUTING.md を参照してください。

ライセンス

MIT