Omnisend MCP Server

Instructions

Implementation Reference

• src/tools/contacts/index.ts:24-48 (handler)

  MCP tool handler for listContacts: calls API helper, filters results, formats as JSON text content with error handling.

  async (args) => {
    try {
      const response = await listContacts(args);
      
      // Filter contacts data to include only defined fields
      const filteredContacts = response.contacts.map(filterContactFields);
      
      return {
        content: [
          { 
            type: "text", 
            text: JSON.stringify({
              contacts: filteredContacts,
              paging: response.paging
            }, null, 2) 
          }
        ]
      };
    } catch (error) {
      if (error instanceof Error) {
        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
      }
      return { content: [{ type: "text", text: "An unknown error occurred" }] };
    }
  }

• src/tools/contacts/index.ts:10-23 (schema)

  JSON Schema for listContacts tool input parameters.

  {
    additionalProperties: false,
    properties: {
      limit: { description: "Maximum number of contacts to return", type: "number" },
      offset: { description: "Skip first N results", type: "number" },
      email: { description: "Filter contacts by email address", type: "string" },
      phone: { description: "Filter contacts by phone number", type: "string" },
      status: { description: "Filter contacts by subscription status", enum: ["subscribed", "unsubscribed", "nonSubscribed"], type: "string" },
      createdAfter: { description: "Filter contacts created after specified date (ISO format)", type: "string" },
      updatedAfter: { description: "Filter contacts updated after specified date (ISO format)", type: "string" },
      tags: { description: "Filter contacts by tags", items: { type: "string" }, type: "array" }
    },
    type: "object"
  },

• src/tools/contacts/index.ts:7-49 (registration)

  Tool registration call for listContacts using McpServer.tool() with name, description, schema, and handler.

  server.tool(
    "listContacts",
    "Retrieve a list of contacts from Omnisend. Each contact can be identified by multiple identifiers (email, phone) with corresponding channels. The response includes pagination information (next/previous cursor, limit, offset).",
    {
      additionalProperties: false,
      properties: {
        limit: { description: "Maximum number of contacts to return", type: "number" },
        offset: { description: "Skip first N results", type: "number" },
        email: { description: "Filter contacts by email address", type: "string" },
        phone: { description: "Filter contacts by phone number", type: "string" },
        status: { description: "Filter contacts by subscription status", enum: ["subscribed", "unsubscribed", "nonSubscribed"], type: "string" },
        createdAfter: { description: "Filter contacts created after specified date (ISO format)", type: "string" },
        updatedAfter: { description: "Filter contacts updated after specified date (ISO format)", type: "string" },
        tags: { description: "Filter contacts by tags", items: { type: "string" }, type: "array" }
      },
      type: "object"
    },
    async (args) => {
      try {
        const response = await listContacts(args);
        
        // Filter contacts data to include only defined fields
        const filteredContacts = response.contacts.map(filterContactFields);
        
        return {
          content: [
            { 
              type: "text", 
              text: JSON.stringify({
                contacts: filteredContacts,
                paging: response.paging
              }, null, 2) 
            }
          ]
        };
      } catch (error) {
        if (error instanceof Error) {
          return { content: [{ type: "text", text: `Error: ${error.message}` }] };
        }
        return { content: [{ type: "text", text: "An unknown error occurred" }] };
      }
    }
  );

• src/api-resources/contacts/index.ts:5-18 (helper)

  Helper function that performs the actual API call to Omnisend /contacts endpoint.

  export const listContacts = async (params: ListContactsParams = {}): Promise<ContactsResponse> => {
    try {
      // Pridėkime trumpą užlaikymą, kad išvengtume daug užklausų per trumpą laiką
      const response = await omnisendApi.get<ContactsResponse>('/contacts', { params });
      return response.data;
    } catch (error) {
      // Pagerinkime klaidos apdorojimą
      if (error instanceof Error) {
        throw new Error(`Error getting contacts list: ${error.message}`);
      } else {
        throw new Error('Unknown error occurred when getting contacts list');
      }
    }
  };

• src/types/contacts/index.ts:42-46 (schema)

  TypeScript interface defining parameters for listContacts, matching the tool schema.

  export interface ListContactsParams {
    limit?: number;
    offset?: number;
    status?: 'subscribed' | 'unsubscribed' | 'nonSubscribed';
  }