ActiveCampaign MCP Server

Instructions

Implementation Reference

• src/tools/contacts.ts:112-133 (handler)

  The primary handler function that performs the API request to retrieve the contact by ID, calls the format helper, and structures the tool response.

  private async getContactById(contactId: string) {
    try {
      const response = await this.apiClient.get(`/api/3/contacts/${contactId}`, {
        params: {
          include: 'fieldValues,tags,contactLists',
        },
      });
  
      const contact = await this.formatContactData(response.data.contact);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(contact, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new Error(`Erro ao buscar contato por ID: ${error instanceof Error ? error.message : 'Erro desconhecido'}`);
    }
  }

• src/tools/contacts.ts:25-38 (schema)

  Tool definition including name, description, and input schema for parameter validation.

  {
    name: 'get_contact_by_id',
    description: 'Busca um contato no ActiveCampaign pelo ID',
    inputSchema: {
      type: 'object',
      properties: {
        contactId: {
          type: 'string',
          description: 'ID do contato a ser buscado',
        },
      },
      required: ['contactId'],
    },
  },

• src/index.ts:62-65 (registration)

  Tool registration in the MCP server's CallToolRequest handler by checking name against contactToolNames and delegating to ContactTools.

  const contactToolNames = ['get_contact_by_email', 'get_contact_by_id', 'search_contacts'];
  if (contactToolNames.includes(name)) {
    return await this.contactTools.executeTool(name, args);
  }

• src/tools/contacts.ts:61-73 (registration)

  Internal registration/dispatch in ContactTools.executeTool via switch case that routes 'get_contact_by_id' to the handler.

  // Executar ferramenta de contato
  async executeTool(name: string, args: any) {
    switch (name) {
      case 'get_contact_by_email':
        return await this.getContactByEmail(args?.email as string);
      case 'get_contact_by_id':
        return await this.getContactById(args?.contactId as string);
      case 'search_contacts':
        return await this.searchContacts(args?.query as string, args?.limit as number);
      default:
        throw new Error(`Ferramenta de contato desconhecida: ${name}`);
    }
  }

• src/tools/contacts.ts:166-229 (helper)

  Supporting helper that enriches raw contact data with human-readable field names, tags, and list information via additional API calls.

  private async formatContactData(rawContact: any): Promise<ActiveCampaignContact> {
    const contact: ActiveCampaignContact = {
      id: rawContact.id,
      email: rawContact.email,
      firstName: rawContact.firstName || '',
      lastName: rawContact.lastName || '',
      phone: rawContact.phone || '',
      cdate: rawContact.cdate,
      udate: rawContact.udate,
    };
  
    // Buscar valores de campos customizados
    if (rawContact.fieldValues) {
      try {
        const fieldsResponse = await this.apiClient.get('/api/3/fields');
        const fields = fieldsResponse.data.fields || [];
        
        contact.fieldValues = rawContact.fieldValues.map((fv: any) => {
          const field = fields.find((f: any) => f.id === fv.field);
          return {
            field: field ? field.title : fv.field,
            value: fv.value,
          };
        });
      } catch (error) {
        console.error('Erro ao buscar campos customizados:', error);
      }
    }
  
    // Buscar tags
    if (rawContact.tags) {
      try {
        const tagsResponse = await this.apiClient.get('/api/3/tags');
        const allTags = tagsResponse.data.tags || [];
        
        contact.tags = rawContact.tags.map((tagId: string) => {
          const tag = allTags.find((t: any) => t.id === tagId);
          return tag ? tag.tag : tagId;
        });
      } catch (error) {
        console.error('Erro ao buscar tags:', error);
      }
    }
  
    // Buscar listas
    if (rawContact.contactLists) {
      try {
        const listsResponse = await this.apiClient.get('/api/3/lists');
        const allLists = listsResponse.data.lists || [];
        
        contact.lists = rawContact.contactLists.map((cl: any) => {
          const list = allLists.find((l: any) => l.id === cl.list);
          return {
            list: list ? list.name : cl.list,
            status: cl.status,
          };
        });
      } catch (error) {
        console.error('Erro ao buscar listas:', error);
      }
    }
  
    return contact;
  }