xaffinity MCP

xaffinity MCP Server

MCP Bash Frameworkを使用して構築された、Affinity CRM 用の MCP（Model Context Protocol）サーバーです。

機能

• エンティティ管理 - 人物、企業、商談を検索・参照します
• ワークフロー管理 - パイプラインのステータスを表示・更新し、リスト項目を管理します
• 関係性インテリジェンス - 関係性の強さを示すスコアを取得し、紹介につながる経路を見つけます
• インタラクションの記録 - 通話、会議、メール、メッセージを記録します
• セッションキャッシュ - API 呼び出しを最小限に抑える効率的なキャッシュ

クイックスタート

# 1. Install the xaffinity CLI
pipx install "affinity-sdk[cli]"

# 2. (Optional) Configure your API key - Claude Desktop will prompt if skipped
xaffinity config setup-key

# 3. Install the MCP server (choose one)
#    - Claude Desktop: Download and double-click xaffinity-mcp-*.mcpb
#    - Other clients: See "Manual Installation" below
#    - Claude Code: /plugin marketplace add yaniv-golan/affinity-sdk

前提条件

Claude Desktop / MCPB へのインストール（推奨）

.mcpb バンドルには MCP Bash Framework と gojq が含まれており、単体で動作します。必要なのは次のものだけです。

要件	インストール方法	確認方法
Python 3.10+	python.org またはパッケージマネージャー	python --version
xaffinity CLI	pipx install "affinity-sdk[cli]"	xaffinity --version
Affinity API key	xaffinity config setup-key（または Claude Desktop のプロンプトに従います）	xaffinity config check-key

CLI と拡張機能のバージョンを揃えてください。 これらは別々にインストールされます。一方をアップグレードしたら、もう一方もアップグレードしてください。pipx upgrade affinity-sdk の後に最新の .mcpb をダウンロードし、逆の場合も同様です。MCP 1.25.2 以降では、拡張機能が必要とするバージョンより古い CLI を使用すると、変更は拒否され（「This MCP server needs the xaffinity CLI … or later to make changes」）、読み取り処理は実行されますが、結果が不完全な可能性があるという警告が表示されます。古い拡張機能と新しい CLI の組み合わせでは、理由が表示されずに失敗することがあります（たとえば、CLI 1.22.0 でマージを行うには、拡張機能 1.25.1 以降が必要です）。Claude Desktop は .mcpb ファイルからインストールした拡張機能を自動更新しません。新しいリリースは、その都度自分でインストールしてください。

手動インストールの場合

手動インストールには追加の依存関係が必要です。

要件	インストール方法	確認方法
Bash 3.2+	macOS/Linux に付属。Windows では WSL または Git Bash を使用	bash --version
Python 3.10+	python.org またはパッケージマネージャー	python --version
jq または gojq	以下の jq/gojq のインストールを参照	jq --version または gojq --version
xaffinity CLI	pipx install "affinity-sdk[cli]"	xaffinity --version
Affinity API key	xaffinity config setup-key	xaffinity config check-key

jq/gojq のインストール

jq と gojq のどちらでも動作します。サーバーが利用可能な方を自動検出します。

選び方：

• jq（推奨）— 広く利用されているオリジナル版で、正規表現を完全にサポートしています
• gojq — Go による実装で、YAML にも対応し、エラーメッセージがより分かりやすくなっています

jq のインストール：

プラットフォーム	コマンド
macOS	brew install jq
Debian/Ubuntu	sudo apt-get install jq
Fedora	sudo dnf install jq
Arch Linux	sudo pacman -S jq
Windows	winget install jqlang.jq または choco install jq

gojq のインストール（代替）：

プラットフォーム	コマンド
macOS	brew install gojq
任意（Go が必要）	go install github.com/itchyny/gojq/cmd/gojq@latest
バイナリのダウンロード	GitHub Releases

インストール

オプション 1：Claude Desktop（ワンクリック）

.mcpb バンドルは完全に自己完結しており、MCP フレームワークと JSON プロセッサが含まれています。

1. xaffinity CLI をインストールします：pipx install "affinity-sdk[cli]"
2. (任意) API キーを設定します：xaffinity config setup-key
   • 省略した場合、MCPB のインストール中に Claude Desktop から API キーの入力を求められます
3. 最新リリースから xaffinity-mcp-*.mcpb をダウンロードします
4. ファイルをダブルクリックするか、Claude Desktop にドラッグします

注： MCPB バンドルは現在、Claude Desktop でのみ動作します。他のクライアントでは手動インストールが必要です。

オプション 2：Claude Code

/plugin marketplace add yaniv-golan/affinity-sdk
/plugin install affinity-crm-mcp-unofficial@xaffinity

オプション 3：手動インストール

他の MCP クライアントや開発向けです。追加の前提条件が必要です。

1. 最新リリースから xaffinity-mcp-plugin.zip をダウンロードします
2. 展開して MCP クライアントを設定します（下記の使い方を参照）
3. MCP Bash Framework のランタイムは .mcp-bash/ に同梱されているため、サーバーの実行に別途インストールする必要はありません。
4. 任意 — 設定を検証します。validate と doctor は開発者向けツールで、完全な mcp-bash のインストールが必要です（同梱されているものはランタイム専用です）。インストールされていない場合、コマンドは固定バージョンのインストールコマンドを表示します：

   ./xaffinity-mcp.sh validate
   

トラブルシューティング

インストールの確認

デバッグを始める前に、各レイヤーが順番に動作することを確認してください。

ステップ 1：CLI のインストール

まず、CLI がインストールされ、Affinity API に接続できることを確認します。CLI：インストールの確認を参照してください。

# Check CLI is installed
xaffinity --version

# Check API connectivity (set your API key - same one entered in Claude Desktop)
AFFINITY_API_KEY="your-key-here" xaffinity whoami --json

whoami が応答しない場合は、ネットワーク接続（ファイアウォール、プロキシ、VPN）を確認してください。

ステップ 2：MCP サーバー

CLI が動作したら、MCP サーバーをエンドツーエンドでテストします。

まず、MCP サーバーのディレクトリを確認します：

# MCPB installation (macOS)
cd ~/Library/Application\ Support/Claude/Claude\ Extensions/local.mcpb.yaniv-golan.xaffinity-mcp/server

# Or find it automatically
cd "$(find ~ -name 'xaffinity-mcp.sh' -type f 2>/dev/null | head -1 | xargs dirname)"

その他のプラットフォーム／インストール方法

インストール方法	パス
MCPB（Windows）	%APPDATA%\Claude\Claude Extensions\local.mcpb.yaniv-golan.xaffinity-mcp\server\
手動インストール	選択した展開先
開発	<repo>/mcp/

MCPB のインストールの場合：ステップ 1 に合格したら、セットアップは完了です。MCP サーバーは CLI を呼び出すため、API キーを使って CLI が動作すれば、MCP サーバーも動作します。Claude Desktop を再起動し、そこでツールをテストしてください。

手動インストールの場合：MCP レイヤーを直接テストすることもできます：

AFFINITY_API_KEY="your-key-here" \
  mcp-bash run-tool execute-read-command \
  --args '{"command":"whoami"}'

期待される結果：ユーザー情報を含む JSON レスポンス。

ステップ 1 が動作してステップ 2 が失敗する場合、問題は MCP 固有です。診断を実行してください（これには同梱ランタイムだけでなく、完全な mcp-bash のインストールが必要です。手動インストールのステップ 4 を参照してください）。

./xaffinity-mcp.sh doctor
./xaffinity-mcp.sh validate

よくある問題

エラー	原因	解決方法
"Could not detect xaffinity CLI"	CLI がインストールされていません	pip install "affinity-sdk[cli]"
"older than this MCP server needs" / "This MCP server needs the xaffinity CLI X or later"	CLI が古くなっています	pipx upgrade affinity-sdk または pip install --upgrade "affinity-sdk[cli]"
"API key not configured"	認証情報がありません	xaffinity config setup-key
"No JSON processor found"	jq/gojq がインストールされていません（手動インストールのみ）	jq/gojq のインストールを参照してください
"Framework not found"	ベンダー化された .mcp-bash/ ディレクトリがありません	cd mcp && mcp-bash vendor
すべてのツール呼び出しが "server.d/policy.sh was not loaded" で失敗する	サーバーのフォルダー、server.d または policy.sh がグループまたはその他のユーザーから書き込み可能になっている（umask 002 でクローンまたは展開した後によく発生します）、シンボリックリンクになっている、または別のユーザーが所有しています。この場合、サーバーはポリシーなしでの実行（読み取り専用モードやその他の制限）を拒否します。	エラーに示されている chmod go-w ... コマンド（または chmod -R go-w <server folder>）を実行してから、サーバーを再起動してください

詳細なデバッグについては、docs/DEBUGGING.mdを参照してください。

使い方

Claude Code を使用する場合

サーバーは .claude-plugin/mcp.json にある Claude プラグインから自動的に利用できます。

その他の MCP クライアントを使用する場合

MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "xaffinity": {
      "command": "/path/to/affinity-sdk/mcp/xaffinity-mcp.sh"
    }
  }
}

ツール

CLI ゲートウェイ（主要インターフェース）

CLI ゲートウェイは、トークンのオーバーヘッドを最小限に抑えながら、xaffinity CLI へのフルアクセスを提供します。

ツール	説明
discover-commands	キーワード（例：「人物を作成」「メモを削除」）で CLI コマンドを検索します
execute-read-command	読み取り専用の CLI コマンド（取得、検索、一覧表示）を実行します
execute-write-command	書き込み用の CLI コマンド（作成、更新、削除）を実行します

クエリツール

ツール	説明
query	フィルター、結合、集計を含む構造化 JSON クエリを実行します

複雑なデータ分析（フィルタリング、グループ化、集計）には、個別の CLI コマンドではなく query ツールを使用してください。詳しくはクエリ言語リファレンスを参照してください。

ユーティリティツール

ツール	説明
get-entity-dossier	エンティティの包括的な情報を取得します（5 回以上の CLI 呼び出しを集約します）
read-xaffinity-resource	静的 MCP リソース（data-model など）を読み取ります

CLI ゲートウェイの使い方

1. 検索して適切なコマンドを見つけます。

   {"query": "add person to list", "category": "write"}
   

   コンパクトなテキスト形式で返されます。

   # cmd|cat|params (s=str i=int b=bool f=flag !=req *=multi)
   list entry add|w|LIST:s! --person-id:i --company-id:i
   

2. コマンドを実行します。

   {"command": "list entry add", "argv": ["Pipeline", "--person-id", "123"]}
   

出力形式

トークン効率を最適化するため、コマンド結果の形式を指定します。

{"command": "person ls", "format": "markdown"}

形式	トークン効率	最適な用途
json	低	プログラムでの使用（デフォルト）
markdown	中〜高	LLM の理解 — 分析タスクに最適
toon	高（約 40% 削減）	大規模データセット、一括操作
csv	中	スプレッドシートへのエクスポート
jsonl	中	ストリーミングワークフロー

推奨事項：

• データの分析や要約が必要な場合は markdown を使用してください（LLM は表を読み取るのが得意です）
• 大規模なエクスポートでトークンを最小限に抑えるには toon を使用してください（JSON より 30〜60% 小さくなります）
• ページネーションやメタデータを含む完全な構造が必要な場合は json を使用してください

破壊的なコマンド

元に戻せないコマンド（削除、統合）を実行するには、ユーザーの確認が必要です。

• 確認ダイアログ（MCP elicitation）に対応しているクライアントでは、サーバーが直接確認を求めます。
• Claude Desktop の拡張機能では、ダイアログは表示されません。 ツールは最初の呼び出しを拒否し、会話の中で確認するよう Claude に伝えます。あなたが同意した後に限り、Claude は confirm: true を指定して再試行します。

{"command": "person delete", "argv": ["456"], "confirm": true}

ツールは CLI に --yes を追加します。MCP 1.27.0 以降では、confirm: true が有効になるのは、サーバーが直近 15 分以内に一度、その正確なコマンドを拒否した場合（またはダイアログを表示した場合）のみです。Claude が最初の呼び出しでこれを指定すると、呼び出しは拒否され、確認するよう Claude に伝えられます。サーバーは会話を確認できないため、あなたが本当に同意したかどうかは判断できません。Claude Desktop のツール承認プロンプトを execute-write-command に対して有効にしておき、「常に許可」は選ばないでください。このプロンプトが、あなたによる確認として必要です。

Affinity 独自のコネクターも使っていますか？ この拡張機能と Affinity の claude.ai コネクターの両方が接続されている場合、Claude はどちらかを選ぶ可能性があります。こちらを使いたい場合は、「xaffinity のツールを使って」と伝えてください。

プロンプト

プロンプト	説明
prepare-briefing	包括的なコンテキストをもとに会議の準備をする
log-interaction-and-update-workflow	やり取りを記録してパイプラインを更新する
pipeline-review	ワークフローパイプラインを確認する
change-status	記録を残してワークフローのステータスを変更する
warm-intro	紹介を受けられる経路を探す
log-call	電話での通話を手早く記録する
log-message	チャットやテキストメッセージを手早く記録する
interaction-brief	やり取りの履歴の要約を取得する

設定

API キー

MCP サーバーは xaffinity CLI を使用します。API キーは次の優先順位（優先度の高い順）で解決されます。

優先順位	ソース	説明
1	--api-key-file	CLI フラグ（ファイルから読み込みます。標準入力の場合は - を指定します）
2	--api-key-stdin	CLI フラグ（標準入力から読み込みます）
3	AFFINITY_API_KEY env var	← Claude Desktop はこれを設定します。--dotenv で読み込んだ .env ファイルからも設定できます
4	AFFINITY_API_KEY_FILE env var	キーを含むファイルへのパス
5	AFFINITY_API_KEY_COMMAND env var	標準出力がキーとなるコマンド
6	設定ファイル	ユーザー設定ファイル内の api_key（xaffinity config path）

MCP サーバーはキーのフラグを渡さないため、MCP サーバーでは環境変数が最初に参照されます。

Claude Desktop / MCPB：Claude Desktop の設定 UI で API キーを入力すると、AFFINITY_API_KEY 環境変数（優先順位 3）として MCP サーバーに渡されます。つまり、次のようになります。

• AFFINITY_API_KEY_FILE、AFFINITY_API_KEY_COMMAND、設定ファイルよりも優先されます
• xaffinity config setup-key でキーを設定したうえで Claude Desktop にもキーを入力すると、Claude Desktop のキーが優先されます

推奨：次の方法のいずれか 1 つを使用してください。

• Claude Desktop のみ：MCPB 設定 UI にキーを入力します（最も簡単です）
• CLI と MCP：xaffinity config setup-key を実行し、Claude Desktop のフィールドは空欄にします
• 環境変数：シェルのプロファイルで AFFINITY_API_KEY を設定します

読み取り専用モード

AFFINITY_MCP_READ_ONLY=1（または true）を設定すると、すべての書き込みツールがブロックされます。Claude Desktop のバンドルでは、これは 読み取り専用モード の設定です。

AFFINITY_MCP_READ_ONLY=1 ./xaffinity-mcp.sh

破壊的なコマンドを無効にする

AFFINITY_MCP_DISABLE_DESTRUCTIVE=1（または true）を設定すると、書き込みは許可しつつ、確認を行っても元に戻せないコマンド（削除、統合）はブロックされます。バンドルでは、これは 破壊的なコマンドを無効にする 設定です。

AFFINITY_MCP_DISABLE_DESTRUCTIVE=1 ./xaffinity-mcp.sh

設定が反映されたか確認するには： Claude に dry-run で person delete 1 を実行するよう依頼してください。読み取り専用が有効な場合は、「Writes are off: the server is in read-only mode」と表示されて拒否されます。破壊的なコマンドが無効な場合は、destructive_disabled が返されます。どちらの場合も変更は行われません。

キャッシュ TTL

キャッシュの保持期間を調整します（デフォルトは 10 分です）。

AFFINITY_SESSION_CACHE_TTL=300 ./xaffinity-mcp.sh

Affinity API のバージョン

デフォルトでは、すべてのリクエストで API キーのデフォルトの Affinity V2 API バージョンが使用されます。バージョンを固定するには（たとえば、最新のレスポンス形式を取得する場合）、AFFINITY_API_VERSION（または Claude Desktop の拡張機能設定にある Affinity API Version フィールド）を設定します。

AFFINITY_API_VERSION=2026-09-17 ./xaffinity-mcp.sh

指定できる値は 2024-01-01、2026-07-15、2026-09-17、または current（常に最新）です。 AFFINITY_PROFILE も引き継がれるため、xaffinity 設定ファイルのプロファイル（api_version を含む）を選択できます。ツールの結果には、応答に使用されたバージョンが meta.affinityApiVersion に報告されます。API バージョンガイドを参照してください。

更新通知

MCP サーバーは起動時に CLI の更新を確認し、新しいバージョンが利用可能な場合は警告を表示します。これにより、CLI コマンドを直接実行しない MCP のみのユーザーも、最新の状態を保てます。

更新確認の特徴：

• ノンブロッキング：確認はバックグラウンドで実行され、サーバーの起動を遅らせません
• 頻度制限：バックグラウンドでの確認は 24 時間に 1 回までです
• ユーザー設定を尊重：XAFFINITY_NO_UPDATE_CHECK=1 または設定ファイルによるオプトアウトに従います

更新通知を無効にするには：

# Via environment variable
XAFFINITY_NO_UPDATE_CHECK=1 ./xaffinity-mcp.sh

# Or via CLI config
xaffinity config update-check --disable

開発

診断の実行

./xaffinity-mcp.sh doctor

デバッグモード

トラブルシューティングのためにデバッグログを有効にします。デバッグモードでは起動時にバージョン情報が表示され、すべてのログメッセージにコンポーネントのプレフィックスが追加されます。

# Persistent debug mode (recommended - survives reinstalls)
mkdir -p ~/.config/xaffinity-mcp && touch ~/.config/xaffinity-mcp/debug

# Session-only via environment variable
XAFFINITY_MCP_DEBUG=1 ./xaffinity-mcp.sh

# Disable persistent debug mode
rm ~/.config/xaffinity-mcp/debug

デバッグモードが有効な場合、ログには次のように表示されます：

[xaffinity-mcp:1.2.3] Debug mode enabled
[xaffinity-mcp:1.2.3] Versions: mcp=1.2.3 cli=0.6.9 mcp-bash=v0.9.3
[xaffinity-mcp:1.2.3] Process: pid=12345 started=2026-01-06T10:30:00-08:00

ログの場所

コンテキスト	ログの場所
Claude Desktop（macOS）	~/Library/Logs/Claude/mcp-server-xaffinity MCP.log
Claude Desktop（Windows）	%APPDATA%\Claude\Logs\mcp-server-xaffinity MCP.log
CLI 単体実行	stderr（コンソール）

高度なデバッグオプション

変数	説明
XAFFINITY_MCP_DEBUG=1	デバッグモードを有効にします（すべてのコンポーネントに適用されます）
MCPBASH_LOG_VERBOSE=true	ログにパスを表示します（ファイルパスが公開されます）
MCPBASH_TRACE_TOOLS=true	ツールのシェルトレース（set -x）を有効にします

詳しいデバッグガイドについては、docs/DEBUGGING.mdを参照してください。

Claude Code プラグイン

この MCP サーバーは Claude Code プラグインとしても利用でき、リポジトリ独自のマーケットプレイス（.claude-plugin/marketplace.json）を通じて配布されます。他のクライアントで MCP サーバーを単体で使用する方法については、メインのMCP ドキュメントを参照してください。

公開する前に、プラグインファイルを組み立てる必要があります。

プラグインのビルド

make plugin

これにより、MCP サーバーのファイルが .claude-plugin/ にコピーされます：

• xaffinity-mcp.sh、xaffinity-mcp-env.sh
• tools/、prompts/、resources/、lib/
• completions/、providers/、scripts/、server.d/

ビルド成果物のクリーンアップ

make clean

プラグインの構成

.claude-plugin/
├── plugin.json          # Plugin manifest (checked in)
├── skills/              # Claude Code skills (checked in)
├── xaffinity-mcp.sh     # MCP server (copied by make)
├── tools/               # MCP tools (copied by make)
├── prompts/             # MCP prompts (copied by make)
└── ...                  # Other MCP files (copied by make)

リリース手順については、CONTRIBUTING.mdを参照してください。

ライセンス

メインリポジトリのライセンスを参照してください。