Attio MCP Server

Attio MCP サーバー

Attio 用の包括的な Model Context Protocol（MCP）サーバーで、CRM の全機能を網羅しています。このサーバーにより、Claude や ChatGPT などの AI アシスタントが自然言語を通じて Attio ワークスペース全体と直接やり取りできます。API を直接呼び出さなくても、商談、タスク、リスト、人物、企業、レコード、メモを管理できます。

🎯 Attio MCP サーバーとは？

AI を活用した自動化で、CRM のワークフローを変革しましょう。複数の画面をクリックして操作する代わりに、Claude や ChatGPT に自然言語で指示するだけで、見込み客の検索、レコードの更新、パイプラインの管理、データの分析ができます。

🎉 v1.0.0 マイルストーン：ChatGPT Developer Mode との完全な統合により、Attio CRM の全機能を網羅しました。

「従業員が50人以上で、過去30日間に連絡していない AI 企業をすべて探して、第1四半期のアウトリーチリストに追加してください」

🚀 ChatGPT Developer Mode との統合

⚠️ Smithery は一時的に利用できません：Smithery はデプロイモデルを変更し、外部ホスティングが必要になりました。ChatGPT ユーザー向けに Cloudflare Worker のホスティングを準備しています。それまでは、ChatGPT からのアクセスやリモートアクセスには Tier 4（Cloudflare Worker）をご利用ください。

ChatGPT Pro/Plus ユーザーは、セルフホストした Cloudflare Worker を通じて、自然言語で Attio のツールセットにアクセスできます。

• 🔐 承認フローを内蔵：MCP の安全性アノテーションにより、読み取り操作は自動承認され、書き込み操作には承認が求められます
• 🌐 OAuth 統合：Cloudflare Worker のデプロイによるセルフホスト型 OAuth
• 💬 自然言語による CRM 操作：会話型 AI を通じて Attio ワークスペース全体を管理
• 📖 セットアップガイド：ChatGPT Developer Mode のドキュメントとCloudflare Worker ガイドをご覧ください

✨ コア機能と実装状況

🎯 ユニバーサルツールアーキテクチャ（19 のユニバーサル操作）

厳選されたツール群：リソースごとに分かれていた40以上のツールをユニバーサル操作に統合し、さらに企業や商談をより安全に更新するため、対象を限定した高頻度の書き込みツールを追加しました。

• 高いパフォーマンス：速度が89.7%向上し、メモリ使用量を227KB削減（PR #483）
• エンタープライズ品質：本番環境への対応度スコア97.15/100、破壊的変更なし
• クリーンなアーキテクチャ：モックファクトリーパターンにより、本番環境とテストを完全に分離
• 構造化された結果：すべてのデフォルトツールが、検証済みの出力スキーマを提示します。リスト、メンバー、診断、コネクターの出力については結果コントラクトをご覧ください。ユニバーサル出力と文章形式のオプトアウトについては、その前のセクションをご覧ください
• 対象を限定したツールの方針：ワークフローの利用頻度が高く、汎用の書き込み操作では誤ったオブジェクトクラスを変更する可能性があり、かつ対象を限定したツールが単にユニバーサル呼び出しの名前を変えるのではなく、モデルによる判断を不要にする場合に限り、対象を限定したデフォルトツールを追加します

📊 機能の実装状況

✅ CRM の全領域を網羅

• 企業：検索、作成、更新、削除、高度な検索、関連検索
• 人物：検索、作成、更新、削除、高度な検索、関連検索
• 取引：インテリジェントなフィールドマッピングとステージ検証を備えた完全な CRUD 操作
• タスク：複数の担当者に対応した作成、更新、削除、検索
• リスト：完全な CRUD 操作、フィルタリング、高度なフィルタリング、エントリー管理
• ノート：すべてのレコードタイプに対応した作成および一覧表示操作
• レコード：すべてのリソースタイプに対応した汎用 CRUD 操作
• 一括操作：チャンク分割とエラー処理を備えた作成、更新、削除
• コンテンツ検索：リソース固有の制限については、対応入力マトリックスをご覧ください
• 関連のナビゲーション：企業↔人物↔取引の双方向の関連
• 高度なフィルタリング：インテリジェントなフィールドマッピングを備えた高度なクエリ機能

📊 企業管理

• 汎用検索：records_search と records_search_advanced で企業を検索
• 対象を絞った書き込み：companies_create と companies_update で企業を作成、更新
• 完全な CRUD：対象を絞ったツールが利用できない場合は、汎用レコード操作で作成、読み取り、更新、削除
• 関連の確認：records_search_by_relationship で企業を検索
• 一括操作：records_batch で数百社を処理
• 詳細情報：records_get_info で連絡先、事業、ソーシャル情報を取得

👥 人物管理

• 汎用の連絡先検索：汎用検索ツールを使って、あらゆる条件で人物を検索
• 関連の追跡：records_search_by_relationship で人物を企業に関連付け
• アクティビティのタイムライン：records_get_interactions でインタラクションのメタデータを取得
• 高度なフィルタリング：汎用フィルタリングによる複数属性検索
• 一括操作：汎用の一括操作で連絡先を効率的に管理

📋 リストとパイプラインの管理（6 個のツール + 非推奨のツール 8 個）

• 有効なツール：自動モード検出機能を備えた統合ツール 4 個（移行ガイド）
  • list_entries_filter - 4 つのモードを備えた統合フィルタリング
  • list_entries_manage - 3 つのモードを備えた統合エントリー管理
  • list_entries_list - リストエントリーを取得
  • records_get_list_memberships - レコードが属するリストを検索
• リスト構成ツール（専用ツール。汎用の records_create／records_update では resource_type: "lists" は受け付けません）：
  • lists_create - 第一級のアクセス制御機能を備えたリストを作成：workspace_access（full-access | read-and-write | read-only | 非公開リストを示す "null"）と workspace_member_access（メンバーごとの権限）。両方のアクセスフィールドを省略すると、新しいリストのアクセス権はワークスペース全体に対する フルアクセス に設定されます。新しいリストには、少なくとも 1 人のフルアクセス権を持つユーザーが必要です。
  • lists_update_configuration - 名前、カスタムフィールド、および同じアクセス制御を更新。メンバーレベルの権限でワークスペースのデフォルト設定を超えるアクセス権を付与できますが、workspace_access で設定されたアクセス権を下回ることはありません。
  • エラーは plan_gating（ワークスペースのプランが要求されたアクセス構成に対応していない）、permission_failure（トークンまたはワークスペースの権限に関する問題）、unsupported_input（アクセス構成の形式が不正）を区別し、それぞれ次のステップを提案します。
• パイプライン操作：取引を営業ステージ間で移動
• スマートなセグメント分け：対象を絞った連絡先リストを作成、管理
• 高度なフィルタリング：AND／OR ロジックによる複雑な複数条件フィルタリング
• エントリー管理：リストへの所属を追加、削除、更新
• 取引の追跡：商談と売上パイプラインを監視
• 取引のデフォルト設定：取引作成を効率化するため、デフォルトのステージ、所有者、通貨を構成可能
• 対象を絞った取引の書き込み：deals_create と deals_update で取引を作成、更新

✅ タスク管理

• 汎用タスク操作：汎用ツールでタスクを作成、更新、管理します
• レコードの関連付け：resource_type パラメーターを使用して、タスクを任意のレコードタイプに関連付けます
• 進捗の追跡：汎用検索とフィルタリングで完了状況を確認します
• チーム連携：一貫した汎用操作でフォローアップを効率化します

🔧 高度な機能

• 一括処理：エラー追跡に対応した一括操作を実行します
• 強化されたフィルタリング：テキスト、数値、日付、ブール値、関連付けによるフィルターと、期間指定検索に対応します（Issue #475）
• データのエクスポート：連携用に JSON 形式でシリアル化します
• リアルタイム更新：Attio とライブデータを同期します

🧠 Claude スキル

よくあるエラーを防ぎ、ベストプラクティスを学べる組み込みスキルで、Claude の Attio に関する知識を強化します。

クイックスタート（「フィールド名が正しくない」エラーを解決します）：

npx attio-discover generate-skill --all --zip
# Import ZIP into Claude Desktop: Settings > Skills > Install Skill

セットアップと使用方法の詳細は、スキルのドキュメントを参照してください。

💬 組み込みプロンプト（10 個のプロンプト）

Claude が CRM データをより効率的に扱えるようにする、便利なショートカットです。

• 検索と発見（5 個）：people_search、company_search、deal_search、meeting_prep、pipeline_health
• アクションの実行（4 個）：log_activity、create_task、advance_deal、add_to_list（ドライランによる安全対策付き）
• 調査と適格性の判定（1 個）：自動ウェブ調査と BANT／CHAMP フレームワークを利用する qualify_lead
• トークン効率：各プロンプトは 300～700 トークンで、一貫した形式を使用します
• 見つけやすさ：タスクに関連するプロンプトを Claude が自動的に提案します

詳しいドキュメントと使用例については、すぐに使えるプロンプトの使用を参照してください。

🎯 すぐに使えるプロンプトの使用

新機能：一般的な Sales ワークフロー向けの、組み込み MCP プロンプトが 10 個あります。セットアップは不要です。すぐに使用できます。

利用可能なプロンプト

簡単な例

# Search for prospects
"Use people_search.v1: Find Account Executives in San Francisco at fintech companies, limit 25"

# Log activity
"Use log_activity.v1: Log a call with Nina at Acme Corp, discussed Q1 pricing, create follow-up task"

# Qualify a lead (with web research)
"Use qualify_lead.v1: Qualify Acme Corp using BANT framework, dry run mode"

# Meeting prep
"Use meeting_prep.v1: Prepare for meeting with contact at Acme Corp"

共通引数

すべての読み取りプロンプトで以下をサポートします。

• format：table | json | ids（デフォルト：table）
• fields_preset：sales_short | full（デフォルト：sales_short）
• verbosity：brief | normal（デフォルト：brief）

すべての書き込みプロンプトで以下をサポートします。

• dry_run：true | false（デフォルト：false）- 実行せずに変更をプレビューします

トークン認識機能

プロンプトには、組み込みのトークン最適化機能があります。

• 予算ガード：プロンプトがトークン制限内に収まります（people_search <500、qualify_lead <400）
• 開発メタデータ：MCP_DEV_META=trueを設定すると、応答にトークン数が表示されます
• テレメトリ：PROMPT_TELEMETRY_ENABLED=trueを設定すると、使用状況がログに記録されます
• 設定可能な制限：MAX_PROMPT_TOKENS環境変数で上書きできます

プロンプトの詳細なドキュメントについては、docs/prompts/v1-catalog.mdを参照してください。

⚠️ 既知の制限事項と重要な注意点

現在の制限事項

• フィールドパラメーターによるフィルタリング：Tasksエンドポイント/objects/tasks/attributesには制限があり、フォールバックパターンで対応しています
• ページネーション：対応パスと上限付きタスク結果については、コレクション継続の契約を参照してください

API互換性

• ユニバーサルツール：主要なインターフェース（19個のツール）であり、新規の統合すべてに推奨されます
• レガシークライアント：削除されたリソース固有ツールと、引き続きサポートされる以前のデフォルトのエイリアスについては、移行ガイドに従ってください
• Lists API：完全なCRUD操作に対応しており、すべての機能が利用できます（一部の古いドキュメントの記述とは異なります）

🤝 OpenAI MCP 互換性

• Developer Mode 対応：すべてのツールで MCP の安全性アノテーション（readOnlyHint、destructiveHint）が公開されるようになりました。これにより、OpenAI Developer Mode は読み取りを自動承認し、書き込みには確認を求められます。
• すべてのツールにアクセス（デフォルト）：完全なカタログがデフォルトで公開されます。現在の一覧を確認するには、MCP の tools/list を使用してください。すべてのツールにアクセスする場合、Smithery の設定で ATTIO_MCP_TOOL_MODE を設定しないでください。
• 検索専用モード：読み取り専用ツール（search、fetch、aaa-health-check）に制限するには、Developer Mode が利用できない場合に、Smithery ダッシュボードで ATTIO_MCP_TOOL_MODE: 'search' を明示的に設定してください。

ツールの機能を確認する（試しに呼び出す必要はありません）

ツールの選択は静的メタデータから判断できるため、クライアントがツールを呼び出してエラーを確認しながら推測する必要はありません。

• capabilities_get（フルモードのみ）は、許可された機能のマニフェストを公開します。このサーバーが公開するすべてのツールについて、入力および出力スキーマに加え、操作情報（アクション、リソースの種類、読み取り専用／破壊的／冪等の各フラグ、認証情報が必要かどうか、ページネーション方式と上限、機能、境界、制限、復旧に関するガイダンス）が含まれます。
• aaa-health-check は、許可されたツールセットについて、操作セクションに絞り込んだ同じマニフェストを返します。これにより、検索専用クライアントは許可リストを広げることなく、使用を許可されたツールを確認できます。スキーマ文書は capabilities_get または tools/list から取得できます。ヘルスチェックのペイロードでは、capabilities.projection にその旨が記載されます。
• どちらも静的です。認証情報を必要とせず、Attio への呼び出しも行いません。また、認証情報が出力やログに含まれることもありません。

一覧に表示されたツールは設定済みであり、許可済みという意味ではありません。すべての呼び出しで引き続き認可が適用されるため、マニフェストの項目が拒否される場合もあります。

• 詳細ガイド：環境変数、承認フロー、検証のヒントについては、docs/chatgpt-developer-mode.md を参照してください。
• ユーザー向けドキュメント：承認フローとセットアップ手順の詳細については、ChatGPT Developer Mode のドキュメントを参照してください。

パフォーマンスに関する考慮事項

• バッチ操作：チャンク分割、レート制限、エラーからの復旧により最適化されています
• 大規模なデータセット：継続処理の仕様を使用して、サポートされているコレクションページを組み合わせます
• レート制限：指数バックオフによる、API のレート制限に対する組み込みの保護機能

トラブルシューティングと解決方法の詳細については、TROUBLESHOOTING.md と GitHub Issues を参照してください。

🎯 高度な検索フィルター

複数の条件による AND／OR フィルタリングで、強力な CRM クエリを作成できます。詳しい例と演算子一覧については、高度な検索ガイドを参照してください。

🚀 インストール

⚠️ 重要：正しいパッケージ名

npm パッケージ名は attio-mcp です（attio-mcp-server ではありません）。 GitHub リポジトリ名は attio-mcp-server ですが、npm パッケージ名は 2025 年 6 月に attio-mcp に変更されました。 attio-mcp-server をインストールすると、レガシーツールが 4 つだけ含まれる古い v0.0.2 リリースがインストールされます。

クライアントの互換性

インストール方法を選択してください：

• ほとんどのユーザー：Tier 1（シェルインストーラー）を使用してください。コマンド1つで自動セットアップできます
• 上級ユーザー：Tier 2（手動）を使用してください。設定を完全に制御できます
• ChatGPT/Teams/Enterprise：Tier 3（Cloudflare Worker）を使用してください。セルフホスト可能で、複数ユーザーに対応するOAuthを利用できます

Tier 1：シェルインストーラー

最適な対象：自動設定を利用してローカルにインストールしたい開発者。

attio-mcpをインストールし、クライアントを自動設定するコマンド1つで実行できるスクリプトです。

Claude Desktop

curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/scripts/install-claude-desktop.sh | bash

Cursor IDE

curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/scripts/install-cursor.sh | bash

Claude Code (CLI)

curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/scripts/install-claude-code.sh | bash

これらのスクリプトは、次の処理を行います。

• 必要に応じてattio-mcp npm パッケージをグローバルにインストールします
• 既存の設定ファイルをバックアップします
• Attio API キーを入力するよう促します
• クライアント用の MCP サーバーを設定します
• 次の手順と再起動の手順を表示します

Tier 2：手動設定

最適な対象：すべてを自分で制御したい上級ユーザー、または未対応のクライアントを使用しているユーザー。

npm install -g attio-mcp

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}

npm install -g attio-mcp

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}

echo '{"command":"attio-mcp","env":{"ATTIO_API_KEY":"your_key_here"}}' | claude mcp add-json attio-mcp --stdin -s user

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}

git clone https://github.com/kesslerio/attio-mcp-server.git
cd attio-mcp-server
npm install
npm run build

ATTIO_API_KEY=your_key node dist/index.js

# Global installation for CLI usage
npm install -g attio-mcp

# Or local installation for project integration
npm install attio-mcp

Tier 3：Cloudflare Worker（リモートデプロイ）

最適な対象：OAuth の一元管理、複数ユーザーのアクセス、モバイルからのアクセス、またはローカルインストールなしでの MCP 実行が必要なチーム。

OAuth 2.1 に完全対応した独自の Attio MCP サーバーを Cloudflare Workers にデプロイします。

モバイルアクセス：リモート MCP サーバーを使うと、次の環境から Attio ツールを利用できます。

• ChatGPT モバイルアプリ（iOS/Android）
• Claude モバイルアプリ（iOS/Android）
• あらゆるデバイスの任意のブラウザー

Cloudflare Worker の機能

クイックデプロイ

cd examples/cloudflare-mcp-server
npm install
wrangler kv:namespace create "TOKEN_STORE"
# Update wrangler.toml with the KV namespace ID
wrangler secret put ATTIO_CLIENT_ID
wrangler secret put ATTIO_CLIENT_SECRET
wrangler secret put TOKEN_ENCRYPTION_KEY
wrangler deploy

クライアントの設定

デプロイ後、Worker URL を使用してクライアントを設定します。

• Claude.ai：設定 → コネクター → Worker URL を追加
• ChatGPT：設定 → コネクター → 開発者モード → Worker URL を追加

次の内容については、Cloudflare Worker Deployment Guide をご覧ください。

• Attio を使用した OAuth 2.1 の完全な設定
• トークン暗号化の設定
• 本番環境へのデプロイチェックリスト
• トラブルシューティングガイド

🆕 v1.4.0 の新機能

主な機能

• 🎯 ワークスペーススキーマスキルジェネレーター (#983) - Attio ワークスペースのスキーマから Claude Skills を自動生成し、フィールド名やオプションのエラーを防止します
• 🔍 選択フィールドトランスフォーマー (#1019) - 選択／ステータスフィールドで、大文字と小文字を区別しない照合、部分一致、UUID の受け渡しに対応します
• 🛠️ Attio スキルジェネレーターのメタスキル (#1020) - ワークスペースのドキュメントを自動作成するメタスキルです
• 📚 汎用使用ガイドスキル (#1018) - ワークフローのパターンとエラー防止策を手作業で作成しました
• ⚙️ records_get_attribute_options ツール (#975) - エラーメッセージを強化し、選択／ステータスフィールドの有効なオプションを取得します
• 📞 電話番号の検証 (#951) - 電話番号の検証に標準で対応します
• ⏱️ オプション取得遅延の設定 - --option-fetch-delay フラグでレート制限を制御できます

主な機能強化

• 🏷️ MCP に準拠したツール名 (#1039) - すべてのツール名で snake_case と動詞を先頭に置く命名方式を採用しました（旧名は v2.0.0 までエイリアス経由で使用できます）
• 🎨 カスタムオブジェクトの表示名 (#1017) - Attio API から表示名を直接取得します
• 📖 インテグレーションパターンの分割 (#1023) - ユースケース別の段階的な探索パターンです
• 💡 属性エラーメッセージの強化 (#975) - 入力ミスに対してレーベンシュタイン距離に基づく候補を提示します

重要な修正

• 📝 メモ内容の改行を保持するよう修正しました (#1052)
• 👤 People 検索で「Unnamed」と表示される問題を修正しました (#1051)
• ✅ 選択フィールドが保持されない問題を修正しました (#1045)
• 🔗 レコード参照の自動変換を修正しました (#997)
• 📊 複数選択配列の自動変換を修正しました (#992)
• 🛡️ 複雑な属性の検証を修正しました (#991)
• ⚠️ フィールドが保持されているのに誤警告が表示される問題を修正しました (#995)
• 📦 SDK の依存関係を固定しました (#1025)
• 💼 Deal のステージ／UTM の検証を修正しました (#1043)
• 📍 Location フィールドの自動正規化を修正しました (#987)

内部改善

• ツールエイリアスシステムのリファクタリング (#1041) - 型安全な定数とパターンベースの生成を採用しました
• CRUD エラーハンドラーに Strategy Pattern を採用しました (#1001)
• メタデータ取得を統合しました (#984)
• UniversalUpdateService をモジュール化しました (#984)
• 選択変換の種類名を変更しました (#1055) - 明確化のため select_title_to_array としました

ツール名

サーバーは、リソースを先頭とするカタログを1つ公開します。search、fetch、aaa-health-check は変更ありません。

以前のデフォルトカタログの名前でも v2.x を通じて同じツールを呼び出せます。これらは tools/list には表示されず、引数も変更されません。MCP_DISABLE_TOOL_ALIASES=true にすると呼び出しは失敗します。これらは v3.0.0 で削除できます。search-records、create-record、records_search_batch など、以前のデフォルトカタログに含まれていなかった名前は直ちに失敗します。

全マッピングは MIGRATION-GUIDE.md と src/constants/tool-names.ts にあります。

⚡ クイックスタート

前提条件

• Node.js（v18 以降）
• Attio API Key（こちらから取得）または OAuth アクセストークン
• Attio Workspace ID

🔐 認証オプション

サーバーは2種類の認証方式に対応しており、どちらも同じ Bearer トークン方式を使用します。

注： 両方が設定されている場合は、ATTIO_API_KEY が優先されます。

OAuth ユーザー： PKCE フローやトークンの更新を含む詳細な設定については、OAuth 認証ガイドを参照してください。

1. 環境変数を設定する

# Option 1: API Key (recommended for most users)
export ATTIO_API_KEY="your_api_key_here"

# Option 2: OAuth Access Token (for OAuth integrations)
# export ATTIO_ACCESS_TOKEN="your_oauth_access_token_here"

export ATTIO_WORKSPACE_ID="your_workspace_id_here"

# Optional: Deal defaults configuration
export ATTIO_DEFAULT_DEAL_STAGE="Interested"           # Default stage for new deals
export ATTIO_DEFAULT_DEAL_OWNER="[email protected]"     # Default owner email address (see below)
export ATTIO_DEFAULT_CURRENCY="USD"                    # Default currency for deal values

2. インストールをテストする

# Test the MCP server
attio-mcp --help

# Discover your Attio workspace attributes
attio-discover attributes

3. 🎯 重要：フィールドマッピングを設定する

MCP サーバーは、自然言語と Attio API のフィールド名を対応させるためにフィールドマッピングファイルを使用します。正しく動作させるには、この設定が不可欠です。

クイックセットアップ

# 1. Copy the sample configuration to create your user config
cp configs/runtime/mappings/sample.json configs/runtime/mappings/user.json

# 2. Edit user.json to match your workspace's custom fields
# Focus on the "objects.companies" and "objects.people" sections

設定ファイル（configs/runtime/mappings/内）

• default.json - Attio CRM の標準フィールド（最初に読み込まれます。編集しないでください）
• sample.json - カスタムフィールドのテンプレート例（ここからコピーして使用します。実行時には使用されません）
• user.json - ワークスペース固有の上書き設定（default.json に追加してマージされます）

💡 重要なポイント： user.jsonはdefault.jsonに追加してマージされるため、上書きと追加項目のみを含めてください。default.jsonにすでに存在するマッピングを重複して記述しないでください。

設定のマージ方法

MCP サーバーは、次の順序で設定を読み込みます。

1. default.json - Attio のすべての標準フィールド（Name、Description、Team など）が含まれます
2. user.json - カスタムの追加項目や上書き設定が、その上にマージされます

例： default.jsonに"Name": "name"があり、user.jsonにも"Name": "name"がある場合、トークンが無駄になります。次のフィールドのみを含めてください。

• 新しいカスタムフィールド（default.json にないもの）
• 異なるマッピング（デフォルトの動作を上書きするもの）

最適化された user.json の例

{
  "mappings": {
    "attributes": {
      "objects": {
        "companies": {
          "// Only your custom fields - defaults are inherited": "",
          "Lead Score": "lead_score",
          "B2B Segment": "b2b_segment",
          "Industry Vertical": "custom_industry_field"
        }
      }
    },
    "lists": {
      "// Only your specific lists": "",
      "Sales Pipeline": "your-pipeline-list-id"
    }
  }
}

✅ 良い例：カスタムフィールドや上書きフィールドのみ
❌ 非効率な例：default.json の標準フィールドを重複して記述

⚠️ 適切なマッピング設定がない場合、MCP サーバーがカスタムフィールドやリストと正しく連携できないことがあります。

次の手順： Claude でテストして、フィールドマッピングが機能することを確認します。

"Find companies in our pipeline with lead score > 80"

4. Claude Desktop を設定する

Claude Desktop の MCP 設定に追加します。

必要な ID を確認する

案件担当者のメールアドレス（案件担当者のデフォルト設定用）：
新しい案件のデフォルト担当者とするワークスペースメンバーのメールアドレスを、ATTIO_DEFAULT_DEAL_OWNERに設定してください。通常はご自身のメールアドレスか、営業チームのリーダーのメールアドレスを指定します。

# Example:
export ATTIO_DEFAULT_DEAL_OWNER="[email protected]"

注： 案件の作成時に、メールアドレスはシステムによってワークスペースメンバーの参照情報に自動的に解決されます。

案件ステージ：
案件ステージはワークスペースごとに異なります。Attio のワークスペース設定を確認するか、discover-attributesコマンドを使用して、案件で利用可能なステージを確認してください。

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here",
        "ATTIO_WORKSPACE_ID": "your_workspace_id_here",
        "ATTIO_DEFAULT_DEAL_STAGE": "Interested",
        "ATTIO_DEFAULT_DEAL_OWNER": "[email protected]",
        "ATTIO_DEFAULT_CURRENCY": "USD"
      }
    }
  }
}

🌟 使用例

営業チーム向け

"Find all companies in the AI space with 50+ employees that we haven't contacted in 30 days"
"Show me all prospects added yesterday"
"Find companies created in the last 7 days with revenue over $10M"
"Create a task to follow up with Microsoft about the enterprise deal"
"Add John Smith from Google to our Q1 prospect list"

マーケティングチーム向け

"Create a list of all SaaS companies who opened our last 3 emails but haven't responded"
"Show me engagement metrics for our outbound campaign this month"
"Add all attendees from the conference to our nurture sequence"

カスタマーサクセス向け

"Show me all enterprise customers with upcoming renewal dates in Q1"
"Create tasks for check-ins with accounts that haven't been contacted in 60 days"
"Find all customers who mentioned pricing concerns in recent notes"

データオペレーション向け

"Update all companies with missing industry data based on their domains"
"Export all contacts added this quarter to CSV"
"Merge duplicate company records for Acme Corporation"

🔐 セキュリティとプライバシー

• 安全な API 認証：業界標準の API キー認証
• データを保存しない：ローカルにデータを保持せず、API に直接中継
• オープンソース：Apache 2.0 ライセンスによる完全な透明性
• オンプレミスにも対応：独自のインフラストラクチャにデプロイ可能
• npm Provenance：Sigstore provenanceを使用して公開されます。すべてのリリースは、暗号学的に GitHub Actions のビルドおよびソースコミットと紐付けられています

サプライチェーンの検証

このパッケージは npm provenance 付きで公開されており、ソースコードから公開された成果物までの検証可能な連鎖が作成されます。リリースを検証するには、次のようにします。

# Check provenance attestation on any published version
npm view attio-mcp --json | jq .attestations

# With pnpm (v10+), enforce trust policy at install time
# pnpm trustPolicy: no-downgrade blocks packages published with weaker credentials

サプライチェーンを最大限に保護するには、pnpm v10+ を使ってインストールしてください。次の機能が適用されます。

• trustPolicy: no-downgrade — 以前のバージョンよりも弱い認証情報で公開されたバージョンをブロックします
• minimumReleaseAge — 新しいバージョンをインストールできるようになるまでのクールダウン期間を設定します

📚 ドキュメント

包括的なドキュメントはdocs ディレクトリにあります。

ユニバーサルツール（推奨）

⚠️ 注意：ユニバーサルツールのドキュメントは、現在の実装に合わせて更新中です。最も正確なインターフェース定義を確認するには、API を直接使用するか、ソースコードを参照してください。

• API の概要 - API の主要な概念とパターン
• ユニバーサルツールのソース - 現在の実装リファレンス
• ツールスキーマ - パラメーターの定義と検証

はじめに

• インストールとセットアップ
• Claude Desktop の設定
• トラブルシューティングガイド

設定

• 警告フィルターの設定 - 表面的な不一致と意味的な不一致、ESLint の予算、抑制方法について
• フィールド検証の設定 - フィールドの永続化検証と検証設定
• 検索スコアリングの設定 - 関連性スコアリング、キャッシュ、オペレーター検証のための環境変数

API リファレンス

📋 実装状況：これらのドキュメントでは Attio API エンドポイントについて説明しています。MCP ツールの使用方法については、上記のユニバーサルツールのドキュメントを参照してください。

• API の概要 - Attio API の一般的な概念
• 会社 API - 会社レコードのエンドポイント ✅ ユニバーサルツールで完全に実装済み
• 人物 API - 人物レコードのエンドポイント ✅ ユニバーサルツールで完全に実装済み
• リスト API - リスト管理のエンドポイント ✅ 完全に実装済み
• メモ API - メモのエンドポイント ✅ 基本実装済み
• タスク API - タスクのエンドポイント ✅ ユニバーサルツールで実装済み

高度なトピック

• バッチ操作 - 一括操作 ✅ チャンク分割を実装済み
• 高度なフィルタリング - 複雑なクエリ ✅ 実装済み
• エラー処理 - エラーのパターン ✅ エラー処理を強化
• MCP の拡張 - カスタマイズガイド

デプロイ

• Docker ガイド
• セキュリティのベストプラクティス

🛠 開発

MCP SDK の互換性

共有サーバーでは、@modelcontextprotocol/server と @modelcontextprotocol/core のバージョン 2.3.1 を正確に指定しています。型とプロトコルエラーは server パッケージから、実行時の Zod プロトコルスキーマは core から取得します。再利用可能な createServer(context?) ファクトリーは、SDK の低レベル Server を返します。CLI はこれを @modelcontextprotocol/server/stdio の StdioServerTransport に接続します。これにより、従来の initialize/serve フローが維持されます。パッケージをアップグレードしても、プロトコルリビジョン 2026-07-28 は有効になりません。

テストでは v2 クライアントを固定しています。旧クライアントとの互換性テスト用に v1 SDK を開発依存関係として維持しており、既存の Worker transport では、トランスポートの移行が完了するまで任意のレガシーピアを維持します。どちらも共有サーバーの第2の実行時オーナーではありません。ドメインの結果スキーマ、コネクターのコンテンツ、再試行不可の不確かな書き込み結果に変更はありません。無効なツールパラメーターには、SDK の InvalidParams（-32602）プロトコルエラーが返されるようになりました。

依存関係を復元した後、SDK 互換性スイートを実行する前にビルドしてください。

bun run build
bun run test:single test/server/sdk-compatibility.test.ts

このスイートでは、両世代の SDK クライアントを使ったビルド済み CLI、公開ライブラリーのエクスポート、およびローカル HTTP フィクスチャに対する Worker のビルド済み共有モジュールのインポートをテストします。サンプルの固定された開発依存関係を復元した後、次も実行してください。

bun run test:sdk:worker

個別の Worker チェックでは、固定された Wrangler/Miniflare ツールチェーンと、nodejs_compat を含むサンプルの 2024-12-01 互換性日付を使用します。一時的なバンドルをビルドし、workerd をローカルでテストします。テスト内容は、セッションの欠落／無効時の拒否、認証済みのレガシー初期化／検出、出力スキーマ、およびインターセプトされた上流に一度だけ送信される不確かな削除です。認証情報や稼働中の CRM へのアクセスは不要です。どちらのチェックも、最新のプロトコルでの提供や本番環境へのデプロイを保証するものではありません。公式の v2 移行ガイドを参照してください。

開発環境のセットアップ

git clone https://github.com/kesslerio/attio-mcp-server.git
cd attio-mcp-server
npm install
npm run build
npm run test:offline

Smithery CLI の開発

Smithery Playground を使ったローカルでの開発とテストについては、次の手順に従ってください。

npm run dev  # Opens Smithery Playground with local server

Smithery CLI の開発環境を詳しくセットアップする方法については、docs/deployment/smithery-cli-setup.mdを参照してください。

テスト

npm test                    # Run all tests
npm run test:offline        # Run only offline tests (no API required)
npm run test:integration    # Integration tests (requires ATTIO_API_KEY)
npm run e2e                 # E2E tests (requires ATTIO_API_KEY)

E2E／統合テストでは、ATTIO_API_KEY を設定した .env を作成してください。詳しいセットアップについては、テストガイドを参照してください。

利用可能なスクリプト

npm run build          # Build TypeScript
npm run test           # Run all tests
npm run test:offline   # Run tests without API calls
npm run analyze:token-footprint # Generate baseline MCP token footprint report
npm run lint           # Check code style
npm run check          # Full quality check
npm run setup:test-data # Create test data for integration tests

🤝 コントリビューション

コントリビューションを歓迎します！詳細については、コントリビューションガイドラインをご覧ください。内容は次のとおりです。

• 新しいツールや機能の追加
• ドキュメントの改善
• バグの報告と機能のリクエスト
• テストと品質保証

📈 今後の予定

この初回リリースは、CRM 自動化の強固な基盤を提供します。

🔗 リンク

• NPM パッケージ：https://www.npmjs.com/package/attio-mcp
• GitHub リポジトリー：https://github.com/kesslerio/attio-mcp-server
• 課題とサポート：https://github.com/kesslerio/attio-mcp-server/issues
• リリース：https://github.com/kesslerio/attio-mcp-server/releases
• Attio ドキュメント：https://developers.attio.com/

📄 ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

原作の帰属表示：このプロジェクトは、@hmk による BSD-3-Clause ライセンスの初期成果を基に、@kesslerio が大幅な変更と機能強化を加えたものです。要件に従い、元の BSD ライセンス表示は LICENSE ファイルに保持されています。

CRM ワークフローを変革する準備はできていますか？ 今すぐ Attio MCP Server をインストールして、AI による CRM 自動化の未来を体験してください！

npm install -g attio-mcp