Apollo.io MCP Server

Instructions

Implementation Reference

• src/index.ts:1000-1091 (handler)

  The main handler function that implements the analyze_list tool. It fetches the contact list and its contacts via Apollo API, analyzes distributions of job titles, seniorities, companies, locations, and calculates data completeness percentages for emails, phones, and LinkedIn profiles. Returns a formatted markdown-style text report.

  private async analyzeList(args: any) {
    // Fetch list details
    const listResponse = await this.axiosInstance.get(`/contact_lists/${args.id}`);
    const list = listResponse.data.contact_list;
  
    // Fetch contacts
    const contactsResponse = await this.axiosInstance.get(
      `/contact_lists/${args.id}/contacts`,
      {
        params: { per_page: 1000 },
      }
    );
    const contacts = contactsResponse.data.contacts || [];
  
    let result = `List Analysis: ${list.name}\n\n`;
    result += `=== Overview ===\n`;
    result += `Total Contacts: ${list.num_contacts || contacts.length}\n`;
    result += `Created: ${list.created_at ? new Date(list.created_at).toLocaleDateString() : "N/A"}\n\n`;
  
    // Analyze job titles
    const titles: { [key: string]: number } = {};
    const seniorities: { [key: string]: number } = {};
    const companies: { [key: string]: number } = {};
    const locations: { [key: string]: number } = {};
    let emailCount = 0;
    let phoneCount = 0;
    let linkedinCount = 0;
  
    contacts.forEach((contact: any) => {
      if (contact.title) {
        titles[contact.title] = (titles[contact.title] || 0) + 1;
      }
      if (contact.seniority) {
        seniorities[contact.seniority] = (seniorities[contact.seniority] || 0) + 1;
      }
      if (contact.account?.name) {
        companies[contact.account.name] = (companies[contact.account.name] || 0) + 1;
      }
      if (contact.city) {
        const location = `${contact.city}, ${contact.state || contact.country || ""}`;
        locations[location] = (locations[location] || 0) + 1;
      }
      if (contact.email) emailCount++;
      if (contact.phone_numbers?.length > 0) phoneCount++;
      if (contact.linkedin_url) linkedinCount++;
    });
  
    result += `=== Data Completeness ===\n`;
    result += `Contacts with Email: ${emailCount} (${((emailCount / contacts.length) * 100).toFixed(1)}%)\n`;
    result += `Contacts with Phone: ${phoneCount} (${((phoneCount / contacts.length) * 100).toFixed(1)}%)\n`;
    result += `Contacts with LinkedIn: ${linkedinCount} (${((linkedinCount / contacts.length) * 100).toFixed(1)}%)\n\n`;
  
    result += `=== Top Job Titles ===\n`;
    Object.entries(titles)
      .sort((a, b) => b[1] - a[1])
      .slice(0, 10)
      .forEach(([title, count]) => {
        result += `${title}: ${count}\n`;
      });
  
    result += `\n=== Seniority Distribution ===\n`;
    Object.entries(seniorities)
      .sort((a, b) => b[1] - a[1])
      .forEach(([seniority, count]) => {
        result += `${seniority}: ${count}\n`;
      });
  
    result += `\n=== Top Companies ===\n`;
    Object.entries(companies)
      .sort((a, b) => b[1] - a[1])
      .slice(0, 10)
      .forEach(([company, count]) => {
        result += `${company}: ${count}\n`;
      });
  
    result += `\n=== Top Locations ===\n`;
    Object.entries(locations)
      .sort((a, b) => b[1] - a[1])
      .slice(0, 10)
      .forEach(([location, count]) => {
        result += `${location}: ${count}\n`;
      });
  
    return {
      content: [
        {
          type: "text",
          text: result,
        },
      ],
    };
  }

• src/index.ts:431-440 (schema)

  Input schema definition for the analyze_list tool, specifying that it requires a string 'id' parameter representing the List ID.

  inputSchema: {
    type: "object",
    properties: {
      id: {
        type: "string",
        description: "List ID to analyze",
      },
    },
    required: ["id"],
  },

• src/index.ts:427-441 (registration)

  Tool registration object for 'analyze_list' in the getTools() method, including name, description, and input schema. This array is returned by the ListToolsRequestSchema handler.

  {
    name: "analyze_list",
    description:
      "Analyze a contact list with detailed breakdown: total contacts, job titles distribution, seniority levels, companies, locations, industries, and data completeness metrics.",
    inputSchema: {
      type: "object",
      properties: {
        id: {
          type: "string",
          description: "List ID to analyze",
        },
      },
      required: ["id"],
    },
  },

• src/index.ts:86-87 (registration)

  Switch case in the CallToolRequestSchema handler that routes 'analyze_list' tool calls to the analyzeList method.

  case "analyze_list":
    return await this.analyzeList(args);