すぐにMCPサーバー

Instantly API v2用の MCP サーバー。電子メール キャンペーンおよびリード管理機能へのアクセスを提供します。

Instantly APIについて

Instantly API v2 は、Instantly プラットフォームのさまざまなリソースと機能へのアクセスを提供する RESTful API です。これには以下が含まれます。

• キャンペーン管理
• リード管理
• メールの取り扱いと検証
• 分析
• アカウント管理
• ブロックリスト管理
• その他

この MCP サーバーは、これらのエンドポイントのサブセットを実装して、最もよく使用される機能に簡単にアクセスできるようにします。

APIリファレンス

完全な Instantly API v2 ドキュメントは、次の場所から入手できます。

• APIエクスプローラー
• APIスキーマ
• 分析エンドポイント

すべての API リクエストのベース URL はhttps://api.instantly.ai/api/v2です。

ツール

この MCP サーバーは、Instantly API v2 エンドポイントにマップされる次のツールを実装します。

1. instantly_create_lead
   • APIエンドポイント: POST /api/v2/leads
   • 新しいリードを作成する
   • 入力:
     • email （文字列）
     • first_name （オプションの文字列）
     • last_name （オプションの文字列）
     • company_name （オプションの文字列）
     • campaign （オプションの文字列、UUID）
     • list_id (オプションの文字列、UUID)
     • personalization （オプションの文字列）
     • website （オプションの文字列）
     • phone （オプションの文字列）
     • custom_variables （オプションのオブジェクト）
2. instantly_get_lead
   • APIエンドポイント: GET /api/v2/leads/{id}
   • IDでリードの詳細を取得する
   • 入力: id (文字列、UUID)
   • 返品: リード詳細
3. instantly_list_leads
   • APIエンドポイント: POST /api/v2/leads/list
   • オプションのフィルターを使用してリードを一覧表示する
   • 入力:
     • campaign （オプションの文字列、UUID）
     • list_id (オプションの文字列、UUID)
     • limit （オプションの数値）
     • starting_after （オプションの文字列）
   • 戻り値: リードの配列
4. instantly_update_lead
   • APIエンドポイント: PATCH /api/v2/leads/{id}
   • リード情報を更新する
   • 入力:
     • id (文字列、UUID)
     • first_name （オプションの文字列）
     • last_name （オプションの文字列）
     • company_name （オプションの文字列）
     • personalization （オプションの文字列）
     • website （オプションの文字列）
     • phone （オプションの文字列）
     • custom_variables （オプションのオブジェクト）
5. instantly_delete_lead
   • APIエンドポイント: DELETE /api/v2/leads/{id}
   • リードを削除する
   • 入力: id (文字列、UUID)
6. instantly_list_campaigns
   • APIエンドポイント: GET /api/v2/campaigns
   • ページ区切りをサポートするリストキャンペーン
   • 入力:
     • limit （オプションの数値、デフォルトは5、最大100）
     • starting_after (オプションの文字列) - ページ区切りには、前のレスポンスのnext_starting_after値を使用します。
     • status （オプションの数字） - キャンペーンをステータスでフィルタリングします（0：下書き、1：アクティブ、2：一時停止、3：完了、4：サブシーケンス実行中）
   • 戻り値: ページ区切り情報を含むキャンペーンの配列
   • ページ番号:
     • 最初のリクエスト: starting_afterなしで呼び出す
     • 後続のページ: 前のレスポンスのnext_starting_after値を使用します
     • ページがなくなると、レスポンスにはnext_starting_after値は含まれません。
   • 例: アクティブなキャンペーンのみを取得するには、 status: 1を使用します。
7. instantly_get_campaign
   • APIエンドポイント: GET /api/v2/campaigns/{id}
   • キャンペーンの詳細を取得する
   • 入力: id (文字列、UUID)
   • 返品：キャンペーンの詳細
8. instantly_get_warmup_analytics
   • APIエンドポイント: POST /api/v2/accounts/warmup-analytics
   • 指定したメールアカウントのウォームアップ分析を取得する
   • 入力: emails (文字列の配列)
   • 戻り値: メールウォームアップパフォーマンスのヘルススコアと指標
   • メールの配信性とアカウントの健全性を監視するのに役立ちます
9. instantly_test_account_vitals
   • APIエンドポイント: POST /api/v2/accounts/test/vitals
   • Instantly ワークスペースでメール アカウントの健全性と接続性をテストします
   • 入力: accounts (文字列の配列) - 複数のメールアドレスを一度にテストできます
   • 戻り値:
     • 全体的なテストステータス
     • 成功したアカウントと失敗したアカウントの概要
     • プロバイダーの詳細を含む各アカウントの詳細情報
     • 失敗したアカウントのトラブルシューティングの推奨事項
   • メールアカウントの設定、認証、API アクセスに関する問題を特定するのに役立ちます
   • 例: {"accounts": ["user@example.com", "sales@company.com"]}
10. instantly_get_campaign_analytics

• APIエンドポイント: GET /api/v2/campaigns/analytics
• 指定した期間のキャンペーンのパフォーマンス指標を取得する
• 入力:
  • id (オプションの文字列) - 特定のキャンペーンのキャンペーンID
  • start_date (文字列) - 開始日（YYYY-MM-DD形式）
  • end_date (文字列) - 終了日（YYYY-MM-DD形式）
• 返品: 開封率、返信率、リード数、商談データなどの包括的な指標

分析エンドポイント

Instantly API は、電子メール キャンペーンとアカウントのパフォーマンスを監視するための強力な分析エンドポイントを提供します。

1. ウォームアップ分析を取得する
   • APIエンドポイント: POST /api/v2/accounts/warmup-analytics
   • 説明: 指定されたメールアカウントのウォームアップ分析データを取得します
   • 必要なスコープ: accounts:read 、 accounts:all 、 all:read 、またはall:all
   • リクエスト本文:
     { "emails": ["user@example.com"] }
   • レスポンス: 送信メール、受信トレイの配置、スパムの配置、受信メールに関する日次データと集計データ、および各アカウントのヘルススコアを提供します。
2. テストアカウントの重要事項
   • APIエンドポイント: POST /api/v2/accounts/test/vitals
   • 説明: メールアカウントの健全性と接続性をテストします
   • 必要なスコープ: accounts:read 、 accounts:all 、 all:read 、またはall:all
   • リクエスト本文:
     { "accounts": ["user@example.com"] }
   • 応答: アカウントのステータスと検出された問題に関する詳細情報を含む成功リストと失敗リストを返します。
3. キャンペーン分析を取得する
   • APIエンドポイント: GET /api/v2/campaigns/analytics
   • 説明: 1つまたは複数のキャンペーンのパフォーマンス指標を取得します
   • クエリパラメータ:
     • id (オプション): 特定のキャンペーンのキャンペーンID
     • start_date : 分析期間の開始日
     • end_date : 分析期間の終了日
   • レスポンス: 以下を含む包括的なキャンペーン統計を返します:
     • 総リード数
     • 連絡したリード数
     • メールの開封数
     • 返信数
     • バウンス数
     • 登録解除数
     • 完了数
     • 送信メール数
     • 新規リードへの連絡数
     • 総機会
     • 総機会価値

リクエスト パラメータと応答形式の詳細については、 Instantly Analytics API ドキュメントを参照してください。

追加のInstantly APIエンドポイント

Instantly API v2 には、この MCP サーバーに実装されていない他の多くのエンドポイントが含まれています。

• キャンペーン管理：
  • キャンペーンの作成: POST /api/v2/campaigns
  • キャンペーンを有効化: POST /api/v2/campaigns/{id}/activate
  • キャンペーンを一時停止する: POST /api/v2/campaigns/{id}/pause
  • キャンペーンを更新: PATCH /api/v2/campaigns/{id}
• メールアドレス:
  • メールへの返信: POST /api/v2/emails/reply
  • メールの一覧表示: GET /api/v2/emails
  • メールを取得: GET /api/v2/emails/{id}
  • 未読メールをカウントする: GET /api/v2/emails/unread/count
• アカウント管理:
  • これらのエンドポイントは、この MCP サーバーでツールとして利用できるようになりました。以下の「アカウント管理ツール」セクションを参照してください。
• メール認証:
  • メールアドレスの確認: POST /api/v2/email-verification
• リードリスト:
  • リストを作成: POST /api/v2/lead-lists
  • リードリストの一覧: GET /api/v2/lead-lists

利用可能なすべてのエンドポイントの完全なリファレンスについては、 Instantly API Explorer を参照してください。

設定

APIキー

Instantly アカウント設定から Instantly API キーを取得します。

1. Instantlyダッシュボードの統合に移動する
2. 左側のサイドバーの「APIキー」セクションをクリックします
3. 「APIキーを作成」ボタンをクリックします
4. APIキーの名前を入力してください
5. このキーにアクセスを許可するスコープを選択します
6. API キーを作成してコピーします (注: 一度だけ表示されます)

Claude Desktopでの使用

claude_desktop_config.jsonに以下を追加します。

ドッカー

NPX

建てる

Dockerビルド:

認証

Instantly API v2はベアラートークン認証を使用します。すべてのリクエストのAuthorizationヘッダーにAPIキーを含める必要があります。

環境変数を通じて API キーを提供すると、MCP サーバーはこれを自動的に処理します。

ライセンス

このMCPサーバーはMITライセンスに基づいてライセンスされています。つまり、MITライセンスの条件に従って、ソフトウェアを自由に使用、改変、配布することができます。詳細については、プロジェクトリポジトリのLICENSEファイルをご覧ください。

アカウント管理ツール

この MCP サーバーは、アカウント管理用に次のツールを実装します。

1. instantly_create_account
   • APIエンドポイント: POST /api/v2/accounts
   • Instantlyで新しいメールアカウントを作成する
   • 入力:
     • email (文字列): アカウントのメールアドレス
     • first_name (文字列): アカウントに関連付けられた名
     • last_name (文字列): アカウントに関連付けられた姓
     • provider_code (数値): プロバイダーコード (1: カスタム IMAP/SMTP、2: Google、3: Microsoft、4: AWS)
     • imap_username (文字列): IMAPユーザー名
     • imap_password (文字列): IMAPパスワード
     • imap_host (文字列): IMAP ホスト (例: imap.gmail.com)
     • imap_port (数字): IMAP ポート (例: 993)
     • smtp_username (文字列): SMTPユーザー名
     • smtp_password (文字列): SMTPパスワード
     • smtp_host (文字列): SMTPホスト (例: smtp.gmail.com)
     • smtp_port (数字): SMTPポート (例: 587)
     • daily_limit （オプションの数値）：1日のメール送信制限
     • tracking_domain_nameドメイン名（オプション文字列）
2. instantly_list_accounts
   • APIエンドポイント: GET /api/v2/accounts
   • 自動ページ区切りでメールアカウントを瞬時にリスト表示
   • 入力:
     • limit （オプションの数値）：ページごとに返されるアカウントの数（最大100、デフォルト10）
     • starting_after (オプションの文字列): 前のページの最後の項目のID - ページ区切りに使用されます
     • search (オプションの文字列): アカウントをフィルタリングするための検索語
     • status （オプションの数字）：ステータスフィルター（1：アクティブ、2：一時停止、-1：接続エラー、-2：ソフトバウンスエラー、-3：送信エラー）
     • provider_code （オプションの数字）：プロバイダーコードフィルター（1：カスタムIMAP/SMTP、2：Google、3：Microsoft、4：AWS）
     • fetch_all （オプションのブール値）：すべてのページを自動的に取得し、包括的な概要を提供するかどうか。すべてのアカウントに関する情報を取得するには、これを使用します。
   • ページ番号:
     • デフォルトの動作: 次のページへのリンクを含む 1 ページの結果を返します
     • fetch_all=trueの場合: すべてのページを自動的に取得し、次の内容を含むすべてのアカウントの包括的な概要を返します。
       • 合計アカウント数
       • プロバイダー別のアカウント分布
       • ステータス別のアカウント分布
       • 参考アカウントのサンプル
3. instantly_get_account
   • APIエンドポイント: GET /api/v2/accounts/{email}
   • 特定のメールアカウントの詳細をすぐに取得する
   • 入力: email (文字列): 取得するアカウントのメールアドレス
4. instantly_update_account
   • APIエンドポイント: PATCH /api/v2/accounts/{email}
   • 既存のメールアカウントをInstantlyで更新する
   • 入力:
     • email (文字列): 更新するアカウントのメールアドレス
     • first_name (オプションの文字列): アカウントに関連付けられた名
     • last_name (オプションの文字列): アカウントに関連付けられた姓
     • daily_limit （オプションの数値）：1日のメール送信制限
     • tracking_domain_nameドメイン名（オプション文字列）
     • skip_cname_check (オプションのブール値): トラッキングドメインのCNAMEチェックをスキップするかどうか
     • remove_tracking_domain (オプションのブール値): アカウントからトラッキングドメインを削除するかどうか
5. instantly_delete_account
   • APIエンドポイント: DELETE /api/v2/accounts/{email}
   • Instantlyからメールアカウントを削除する
   • 入力: email (文字列): 削除するアカウントのメールアドレス
6. instantly_pause_account
   • APIエンドポイント: POST /api/v2/accounts/{email}/pause
   • Instantlyでメールアカウントを一時停止する
   • 入力: email (文字列): 一時停止するアカウントのメールアドレス
7. instantly_resume_account
   • APIエンドポイント: POST /api/v2/accounts/{email}/resume
   • 一時停止したメールアカウントをInstantlyで再開する
   • 入力: email (文字列): 再開するアカウントのメールアドレス

ツールのテスト状況

このMCPサーバーに実装されているすべてのツールは、Instantly API v2で正常に動作することを確認するために徹底的にテストされています。テスト状況の概要は以下の通りです。

テストプロセスと結果の詳細については、リポジトリのTesting.md を参照してください。

既知の問題

• 現時点では、 instantly_list_leadsツールは、特定のメールフィルターを指定せずにリードリストを作成しようとすると、「無効なメールアドレス」というAPIエラーを返します。この問題を解決するために、以下の方法を含む複数の方法を試しました。
  • メール検索にcontacts配列パラメータを使用する
  • 空のリクエストボディによる自動再試行の実装
  • さまざまなパラメータのフォーマット方法 今後のリリースでもこの問題の解決に取り組んでいきます。

開発のためのセットアップ

このプロジェクトに貢献したり、開発のためにローカルで実行したりしたい場合は、次の手順に従ってください。

1. リポジトリをクローンします。
   git clone https://github.com/bcharleson/Instantly-MCP.git cd Instantly-MCP
2. 依存関係をインストールします:
   npm install
3. Instantly API キーを使用してルート ディレクトリに.envファイルを作成します。
   INSTANTLY_API_KEY=your_api_key_here

   ⚠️重要： .envファイルや API キーをバージョン管理にコミットしないでください。.env ファイルは.gitignore .env含まれています。

4. プロジェクトをビルドします。
   npm run build
5. サーバーを実行します。
   node dist/index.js

貢献

貢献大歓迎！貢献したい場合は：

1. リポジトリをフォークする
2. 機能ブランチを作成する ( git checkout -b feature/amazing-feature )
3. 変更を加える
4. 変更をコミットします ( git commit -m 'Add some amazing feature' )
5. ブランチにプッシュする ( git push origin feature/amazing-feature )
6. プルリクエストを開く

プルリクエストを送信する前に、次の点を確認してください。

• コードはプロジェクトのコーディングスタイルに従っている
• 新しい機能のテストを追加しました
• すべてのテストに合格
• 必要に応じてドキュメントを更新しました