Omnisend MCP Server

Omnisend MCP サーバー

TypeScript で記述された、Omnisend API V5 と連携する Model Context Protocol（MCP）サーバーです。

バージョン： 2.3.0

機能

• 連絡先の管理（一覧表示、作成、取得、更新）
• 商品の管理（一覧表示、作成、取得、置換、削除）
• イベントの追跡
• 商品カテゴリーの管理
• ブランド情報へのアクセス
• 次／前の URL と limit／offset 情報を含むカーソルベースのページネーションに対応
• デバッグとテストのための MCP Inspector 連携
• 適切な JSON スキーマ応答を備えた、人が読みやすいリソース名

バージョン 2.3.0 の変更点

• /v5/brands/current エンドポイントとの連携によるブランド情報のサポートを追加
• 現在のブランドデータを取得する getCurrentBrand ツールを実装
• 最新のブランドデータにアクセスするための Brand information リソースを追加
• 適切な JSON スキーマ定義を備えた Brand schema リソースを追加
• すべてのスキーマリソースを更新し、ダミーテキストの代わりにシリアライズ済み JSON を返すように変更
• 人が読みやすい名前と「schema」サフィックスを付け、リソース名を改善
• npm run inspect および npm run inspect:env スクリプトによる MCP Inspector 連携を追加
• ビジュアルテストインターフェースにより、デバッグ機能を強化
• 包括的なデバッグおよびテストガイドを追加して、ドキュメントを更新

バージョン 2.2.0 の変更点

• コードベースをよりモジュール化された構成にリファクタリング
• ドメイン固有のモジュール（連絡先、商品、カテゴリー、イベント）を実装
• コードを論理的なディレクトリ（/types、/filters、/api-resources、/resources、/tools）に整理
• ping ツールでサーバーのバージョンを動的に取得するように変更
• API リクエストのエラー処理を改善
• バレルエクスポートによりコードの保守性を向上
• 冗長なコードや重複したコードを削除

バージョン 2.1.0 の変更点

• @modelcontextprotocol/sdk を v1.11.0 に更新
• アプリケーション全体のエラー処理を改善
• エラーメッセージを改善し、API の安定性を強化
• 接続がハングするのを防ぐリクエストタイムアウト設定を追加
• MCP Inspector での SSE 接続の問題を修正
• MCP クライアントとの互換性を高めるため、コンソール出力を最適化
• MCP 応答にカーソルベースのページネーションコンテキスト（次／前の URL、limit／offset）を追加

バージョン 2.0.0 の変更点

• コードベース全体を TypeScript に移行
• 最新の仕様に沿って MCP リソース構造を更新
• すべての API 応答とリクエストに適切な型宣言を追加
• 型付き例外によってエラー処理を改善
• コードの構成と保守性を強化

インストール

npm install

ビルド

TypeScript コードをコンパイルするには：

npm run build

開発モードでの実行

自動再読み込みを有効にして開発するには：

npm run dev

デバッグとテスト

MCP Inspector

このプロジェクトには、テストとデバッグ用に MCP Inspector を実行するスクリプトが含まれています：

# Basic inspector (requires .env file or environment variables)
npm run inspect

# Inspector with explicit environment variables
OMNISEND_API_KEY=your_api_key npm run inspect:env

MCP Inspector では、次のことができます：

• すべてのツールとリソースを対話形式でテスト
• MCP 通信をリアルタイムでデバッグ
• サーバーの機能を確認できるビジュアルインターフェース
• リクエスト／応答のログ記録とエラー分析

Inspector はブラウザーで開き（通常は http://localhost:6274）、次の操作ができます：

• 利用可能なすべてのツール（ping、連絡先、商品、カテゴリー、イベント、ブランド）をテスト
• リソース（スキーマと最新データ）を閲覧
• サーバーログと通知を監視
• 他の MCP クライアントで使用する設定をエクスポート

設定

Omnisend API キーを記載した .env ファイルをルートディレクトリに作成します：

OMNISEND_API_KEY=your_api_key_here
OMNISEND_API_URL=https://api.omnisend.com/v5

使用方法

MCP サーバーを起動するには：

npm start

MCP サーバーとの対話

この MCP サーバーは、Model Context Protocol を理解するクライアントで使用するように設計されています。 次の方法で対話できます：

VS Code との連携

VS Code で使用するための設定ファイルが .vscode/mcp.json に用意されています。 適切な MCP 拡張機能を備えた VS Code から、このサーバーと通信できます。

AI アシスタント

MCP に対応した Claude などの AI アシスタントは、このサーバーと通信して Omnisend のデータにアクセスし、操作を実行できます。

Claude Desktop での使用

この MCP サーバーを Claude Desktop で使用するには、次の手順に従います。

1. 公式サイトから Claude Desktop をダウンロードしてインストールします。

2. システムに Node.js がインストールされていることを確認します。次のコマンドを実行すると確認できます。

   node --version
   

   Node.js がインストールされていない場合は、nodejs.orgからダウンロードします。

3. コンピューターで Claude メニューを開き、「Settings...」を選択します。

4. Settings ペインの左側にある「Developer」をクリックし、「Edit Config」をクリックします。

5. Claude Desktop の設定ファイルが開きます。ファイルの内容を次の設定に置き換えるか、次の設定を追加します。

   {
     "mcpServers": {
       "omnisend": {
         "command": "node",
         "args": [
           "/path/to/dist/index.js"
         ],
         "env": {
           "OMNISEND_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   

   your_api_key_here を実際の Omnisend API キーに置き換えてください。

6. 設定ファイルを保存し、Claude Desktop を再起動します。

7. 再起動後、入力ボックスの右下にハンマーのアイコンが表示されます。

8. ハンマーのアイコンをクリックすると、利用可能な Omnisend ツールが表示されます。

9. Claude に次のような操作を依頼できます。

   • 「Omnisend の最近の連絡先を一覧表示して」
   • 「Omnisend のカタログに新しい商品を作成して」
   • 「顧客イベントを Omnisend に送信して」

カスタム MCP クライアント

@modelcontextprotocol/sdk ライブラリを使用して、カスタムクライアントを開発できます。

import { McpClient } from '@modelcontextprotocol/sdk/client/mcp';
import { ProcessClientTransport } from '@modelcontextprotocol/sdk/client/process';

const transport = new ProcessClientTransport(serverProcess);
const client = new McpClient(transport);

// Connect to the server
await client.connect();

// Execute tools
const result = await client.executeTool("listContacts", { limit: 10 });

API ドキュメント

Omnisend API の詳細については、公式ドキュメントを参照してください。

ライセンス

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