Omnisend MCP Integration Server

This repository contains the source code for an MCP (Model Context Protocol) gateway server, engineered in TypeScript, designed to facilitate seamless interaction with the Omnisend API (specifically V5 endpoints).

Current Release: 2.3.0

Core Capabilities

• Subscriber/Contact Handling: Full CRUD operations for managing user profiles within Omnisend.
• Product Inventory Sync: Tools for listing, creation, retrieval, replacement, and removal of product entities.
• Behavioral Event Ingestion: Functionality to dispatch custom tracking events.
• Product Group Management: Administration of product categorization structures.
• Brand Configuration Access: Read access to the currently configured brand metadata.
• Advanced Pagination: Adherence to cursor-based data fetching patterns, providing 'next' and 'previous' navigation links along with control parameters (limit/offset).
• Debugging Suite: Native integration with the MCP Inspector utility for diagnostics and testing.
• Semantic Clarity: Utilizes human-readable names for resources, paired with accurate JSON Schema definitions for data contracts.

Release Notes (v2.3.0)

• Incorporated support for retrieving active brand configuration via the /v5/brands/current endpoint.
• Introduced the dedicated getCurrentBrand invocation tool.
• Added a 'Brand information' resource path for real-time brand data access.
• Established a formal 'Brand schema' resource definition.
• Significantly upgraded all resource schemas to output valid, serialized JSON output rather than placeholder text.
• Refined resource nomenclature for improved readability, appending the "schema" suffix where appropriate.
• Integrated MCP Inspector startup scripts (npm run inspect and npm run inspect:env).
• Upgraded debugging workflow and documentation for visual testing.
• Enhanced accompanying documentation to cover testing and debugging protocols comprehensively.

Release Notes (v2.2.0)

• Major refactoring: Restructured codebase into a highly modular architecture.
• Implemented dedicated domain modules for contacts, products, categories, and events.
• Organized source files into logical directories: /types, /filters, /api-resources, /resources, /tools.
• Dynamic server version reporting implemented in the ping tool response.
• Strengthened fault tolerance within API request handling routines.
• Improved code maintainability via centralized barrel exports.
• Eliminated instances of duplicated or unnecessary code segments.

Release Notes (v2.1.0)

• Dependency update: Migrated to @modelcontextprotocol/sdk version 1.11.0.
• System-wide enhancement of exception management.
• Improved API resilience through clearer, more informative error messaging.
• Introduced request timeouts to mitigate indefinitely hanging connections.
• Resolved issues concerning Server-Sent Events (SSE) connections with the MCP Inspector.
• Optimized console verbosity for better compatibility with various MCP client implementations.
• Standardized cursor-based pagination metadata inclusion within MCP responses (next/previous URIs, limit/offset data).

Release Notes (v2.0.0)

• Complete project migration from JavaScript to TypeScript.
• Updated resource structure to comply with the most recent MCP specification guidelines.
• Implemented rigorous type definitions for all incoming requests and outgoing responses.
• Bolstered error handling mechanisms using strongly-typed exception classes.
• Significantly improved overall code structure and long-term maintainability.

Setup Instructions

To initialize dependencies:

bash npm install

Compilation

To build the TypeScript source code into deployable JavaScript:

bash npm run build

Local Development Workflow

To run the server with live-reloading enabled:

bash npm run dev

Diagnostics and Testing

Utilizing the MCP Inspector

The integrated scripts facilitate the launch of the MCP Inspector for testing and debugging purposes:

bash

Standard inspector launch (relies on .env file or environment variables)

npm run inspect

Inspector launch forcing environment variable configuration

OMNISEND_API_KEY=your_api_key npm run inspect:env

The Inspector environment offers: - Interactive execution paths for every exposed tool and resource. - Low-level debugging of MCP communication streams. - A visual dashboard for exploring server capabilities. - Detailed logging of requests, responses, and error traces.

The inspector typically launches at http://localhost:6274, allowing users to: - Execute tests against all registered tools (ping, contacts, products, categories, events, brands). - Navigate and inspect resource definitions (schemas) and live data payloads. - Monitor server activity streams. - Generate configuration exports for external MCP consumers.

Environment Configuration

Define your Omnisend API credentials by creating a .env file in the project root:

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

Launching the Server

Initiate the MCP gateway service using:

bash npm start

Interacting with the Gateway

The MCP server is designed to interface with clients built around the Model Context Protocol standard.

VS Code Integration

VS Code users can leverage the server via the configuration file located at .vscode/mcp.json, assuming the requisite MCP extension is installed.

AI Agent Consumption

Assistants, such as Claude, equipped with MCP support, can leverage this gateway to query Omnisend data and execute automation tasks.

Integration with Claude Desktop

To integrate this service with the Claude Desktop application:

1. Secure and install Claude Desktop from the official source.

2. Verify that Node.js is available on your system by checking the version:

bash node --version

If Node.js is absent, download and install it from nodejs.org.

1. Access the Claude application menu and navigate to "Settings...".

2. Select "Developer" from the sidebar, then click "Edit Config".

3. Substitute or append the following configuration block into your Claude Desktop configuration file:

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

Ensure /path/to/dist/index.js points to the compiled entry point and update the placeholder API key.

1. Save the configuration and restart Claude Desktop.

2. Upon relaunch, a wrench/hammer icon should appear near the input field.

3. Interact with the tools by prompting Claude with requests such as:

4. "Fetch the ten most recent customer entries from Omnisend."
5. "Provision a new item into the Omnisend product catalog."
6. "Record a recent customer interaction event in Omnisend."

Developing Custom MCP Clients

Custom client applications can be developed utilizing the @modelcontextprotocol/sdk package:

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

// Assuming 'serverProcess' is an object representing the server's spawned process const transport = new ProcessClientTransport(serverProcess); const client = new McpClient(transport);

// Establish connection await client.connect();

// Invoke a specific tool const response = await client.executeTool("listContacts", { limit: 10 });

Omnisend API Reference

For detailed specifications on the underlying Omnisend REST API, refer to the official documentation.

Licensing

This software is distributed under the terms of the Apache License, Version 2.0. See the LICENSE file for full details.