Omnisend MCP Server

Instructions

Implementation Reference

• src/tools/contacts/index.ts:68-89 (handler)

  The inline handler function for the createContact MCP tool. It calls the createOrUpdateContact API wrapper, filters the response using filterContactFields, and returns JSON stringified result or error.

  async (args) => {
    try {
      const response = await createOrUpdateContact(args.contactData);
      
      // Filter contact data to include only defined fields
      const filteredContact = filterContactFields(response);
      
      return {
        content: [
          { 
            type: "text", 
            text: JSON.stringify(filteredContact, 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:55-67 (schema)

  Input schema for the createContact tool, defining contactData as an open object.

  {
    additionalProperties: false,
    properties: {
      contactData: { 
        additionalProperties: true,
        description: "Contact data", 
        properties: {},
        type: "object"
      }
    },
    required: ["contactData"],
    type: "object"
  },

• src/tools/contacts/index.ts:52-90 (registration)

  Registration of the createContact tool using server.tool(), including name, description, input schema, and handler function.

  server.tool(
    "createContact",
    "Create or update a contact in Omnisend. Contact data can include identifiers (email, phone), personal information, subscription status, and custom properties.",
    {
      additionalProperties: false,
      properties: {
        contactData: { 
          additionalProperties: true,
          description: "Contact data", 
          properties: {},
          type: "object"
        }
      },
      required: ["contactData"],
      type: "object"
    },
    async (args) => {
      try {
        const response = await createOrUpdateContact(args.contactData);
        
        // Filter contact data to include only defined fields
        const filteredContact = filterContactFields(response);
        
        return {
          content: [
            { 
              type: "text", 
              text: JSON.stringify(filteredContact, 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:21-32 (helper)

  API wrapper function that performs the POST request to Omnisend /contacts endpoint to create or update a contact.

  export const createOrUpdateContact = async (contactData: Partial<Contact>): Promise<Contact> => {
    try {
      const response = await omnisendApi.post<Contact>('/contacts', contactData);
      return response.data;
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Error creating contact: ${error.message}`);
      } else {
        throw new Error('Unknown error occurred when creating contact');
      }
    }
  };

• src/filters/contacts/index.ts:2-21 (helper)

  Helper function to filter contact object to specific allowed fields before returning in tool response.

  export const filterContactFields = (contact: any) => {
    return {
      contactID: contact.contactID,
      email: contact.email,
      phone: contact.phone,
      firstName: contact.firstName,
      lastName: contact.lastName,
      status: contact.status,
      tags: contact.tags,
      identifiers: contact.identifiers,
      createdAt: contact.createdAt,
      updatedAt: contact.updatedAt,
      // Include added fields
      country: contact.country,
      state: contact.state,
      city: contact.city,
      gender: contact.gender,
      birthdate: contact.birthdate
    };
  }; 

• src/types/contacts/index.ts:17-34 (schema)

  TypeScript interface defining the structure of a Contact object, used in API calls and filtering.

  export interface Contact {
    contactID: string;
    email?: string;
    phone?: string;
    firstName?: string;
    lastName?: string;
    status?: string;
    tags?: string[];
    identifiers?: ContactIdentifier[];
    createdAt?: string;
    updatedAt?: string;
    country?: string;
    state?: string;
    city?: string;
    gender?: string;
    birthdate?: string;
    [key: string]: unknown;
  }