Omnisend MCP Server

Omnisend MCP 服务

一个使用 TypeScript 编写的 Model Context Protocol（MCP）服务，可与 Omnisend API V5 集成。

版本： 2.3.0

功能

• 联系人管理（列表、创建、获取、更新）
• 产品管理（列表、创建、获取、替换、删除）
• 事件跟踪
• 产品类别管理
• 品牌信息访问
• 支持基于游标的分页，并提供下一页／上一页 URL 以及 limit／offset 信息
• 集成 MCP Inspector，便于调试和测试
• 提供易读的资源名称，并返回规范的 JSON schema 响应

2.3.0 版本变更

• 通过集成 /v5/brands/current 端点，添加品牌信息支持
• 实现 getCurrentBrand 工具，用于获取当前品牌数据
• 添加 Brand information 资源，用于访问实时品牌数据
• 添加 Brand schema 资源，并提供规范的 JSON schema 定义
• 更新所有 schema 资源，使其返回序列化 JSON，而非虚拟文本
• 改进资源命名，采用易读名称并添加“schema”后缀
• 添加 MCP Inspector 集成，并提供 npm run inspect 和 npm run inspect:env 脚本
• 通过可视化测试界面增强调试能力
• 更新文档，添加全面的调试和测试指南

2.2.0 版本变更

• 将代码库重构为更模块化的结构
• 实现特定领域模块（联系人、产品、类别、事件）
• 将代码整理到逻辑目录（/types、/filters、/api-resources、/resources、/tools）中
• 使 ping 工具中的服务版本动态化
• 改进 API 请求中的错误处理
• 通过 barrel exports 提高代码可维护性
• 移除冗余和重复代码

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、联系人、产品、类别、事件、品牌）
• 浏览资源（schema 和实时数据）
• 监控服务日志和通知
• 导出配置，以便与其他 MCP 客户端配合使用

配置

在根目录中创建 .env 文件，并填入 Omnisend API 密钥：

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 文件。