Build Your Own MCP Server: Complete Guide

# Create project directory
mkdir hunter-mcp
cd hunter-mcp

# Initialize npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

# Create source directory
mkdir src

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

{
  "type": "module",
  "bin": {
    "hunter-mcp": "./build/index.js"
  },
  "scripts": {
    "build": "tsc",
    "start": "node build/index.js"
  }
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Hunter.io API configuration
const HUNTER_API_BASE = "https://api.hunter.io/v2";
const API_KEY = process.env.HUNTER_API_KEY;

// Validate API key exists
if (!API_KEY) {
  console.error("HUNTER_API_KEY environment variable is required");
  console.error("Get your free API key at https://hunter.io");
  process.exit(1);
}

// Create server instance
const server = new McpServer({
  name: "hunter",
  version: "1.0.0",
});

// Helper function for Hunter API requests
async function hunterRequest<T>(endpoint: string, params: Record<string, string> = {}): Promise<T | null> {
  const url = new URL(`${HUNTER_API_BASE}${endpoint}`);
  url.searchParams.set("api_key", API_KEY!);

  // Add any additional params
  for (const [key, value] of Object.entries(params)) {
    url.searchParams.set(key, value);
  }

  try {
    const response = await fetch(url.toString());

    if (!response.ok) {
      const error = await response.json();
      console.error(`Hunter API error: ${error.errors?.[0]?.details || response.statusText}`);
      return null;
    }

    const result = await response.json();
    return result.data as T;
  } catch (error) {
    console.error("Request failed:", error);
    return null;
  }
}

// Type definitions for Hunter.io API responses
interface DomainSearchResult {
  domain: string;
  disposable: boolean;
  webmail: boolean;
  accept_all: boolean;
  pattern: string | null;
  organization: string | null;
  emails: Array<{
    value: string;
    type: string;
    confidence: number;
    first_name: string | null;
    last_name: string | null;
    position: string | null;
    department: string | null;
    linkedin: string | null;
    twitter: string | null;
    phone_number: string | null;
  }>;
}

interface EmailFinderResult {
  first_name: string;
  last_name: string;
  email: string;
  score: number;
  domain: string;
  position: string | null;
  twitter: string | null;
  linkedin_url: string | null;
  company: string | null;
}

interface EmailVerifierResult {
  email: string;
  status: "valid" | "invalid" | "accept_all" | "webmail" | "disposable" | "unknown";
  result: "deliverable" | "undeliverable" | "risky" | "unknown";
  score: number;
  regexp: boolean;
  gibberish: boolean;
  disposable: boolean;
  webmail: boolean;
  mx_records: boolean;
  smtp_server: boolean;
  smtp_check: boolean;
  accept_all: boolean;
  block: boolean;
}

// Tool 1: Domain Search - Find emails at a company
server.tool(
  "domain_search",
  "Find email addresses associated with a company domain. Returns names, positions, and confidence scores.",
  {
    domain: z.string().describe("Company domain to search (e.g., 'stripe.com')"),
    limit: z.number().optional().default(10).describe("Max results to return (default 10, max 100)")
  },
  async ({ domain, limit }) => {
    const data = await hunterRequest<DomainSearchResult>("/domain-search", {
      domain,
      limit: String(Math.min(limit, 100))
    });

    if (!data) {
      return {
        content: [{ type: "text", text: `Could not search domain: ${domain}. Check if the domain is valid.` }]
      };
    }

    if (data.emails.length === 0) {
      return {
        content: [{ type: "text", text: `No emails found for ${domain}. This could mean:\n- The domain has no public emails\n- Hunter hasn't indexed this domain yet` }]
      };
    }

    // Format the results
    const emailList = data.emails.map(email => {
      const name = [email.first_name, email.last_name].filter(Boolean).join(" ") || "Unknown";
      const role = email.position || email.department || "Unknown role";
      const confidence = email.confidence;

      let extras = [];
      if (email.linkedin) extras.push(`LinkedIn: ${email.linkedin}`);
      if (email.phone_number) extras.push(`Phone: ${email.phone_number}`);

      return `- ${email.value}
  Name: ${name}
  Role: ${role}
  Confidence: ${confidence}%${extras.length ? "\n  " + extras.join("\n  ") : ""}`;
    }).join("\n\n");

    const summary = `
Domain: ${data.domain}
Organization: ${data.organization || "Unknown"}
Email Pattern: ${data.pattern || "Unknown"}
Accept-All: ${data.accept_all ? "Yes (can't verify individual emails)" : "No"}

Found ${data.emails.length} emails:

${emailList}
    `.trim();

    return {
      content: [{ type: "text", text: summary }]
    };
  }
);

// Tool 2: Email Finder - Find a specific person's email
server.tool(
  "email_finder",
  "Find the email address of a specific person at a company. Provide their name and company domain.",
  {
    domain: z.string().describe("Company domain (e.g., 'stripe.com')"),
    first_name: z.string().describe("Person's first name"),
    last_name: z.string().describe("Person's last name")
  },
  async ({ domain, first_name, last_name }) => {
    const data = await hunterRequest<EmailFinderResult>("/email-finder", {
      domain,
      first_name,
      last_name
    });

    if (!data || !data.email) {
      return {
        content: [{
          type: "text",
          text: `Could not find email for ${first_name} ${last_name} at ${domain}.

Possible reasons:
- Person doesn't exist at this company
- Email pattern not found
- Name spelling might be different

Try:
- Check LinkedIn for correct spelling
- Try domain_search to see all emails at ${domain}`
        }]
      };
    }

    let extras = [];
    if (data.position) extras.push(`Position: ${data.position}`);
    if (data.linkedin_url) extras.push(`LinkedIn: ${data.linkedin_url}`);
    if (data.twitter) extras.push(`Twitter: @${data.twitter}`);

    const result = `
Found email for ${data.first_name} ${data.last_name}:

Email: ${data.email}
Confidence: ${data.score}%
Domain: ${data.domain}
${extras.length ? "\n" + extras.join("\n") : ""}

Note: ${data.score >= 90 ? "High confidence - likely accurate" : data.score >= 70 ? "Medium confidence - probably accurate" : "Low confidence - verify before using"}
    `.trim();

    return {
      content: [{ type: "text", text: result }]
    };
  }
);

// Tool 3: Email Verifier - Check if an email is valid
server.tool(
  "email_verifier",
  "Verify if an email address is valid and deliverable. Returns detailed verification results.",
  {
    email: z.string().email().describe("Email address to verify")
  },
  async ({ email }) => {
    const data = await hunterRequest<EmailVerifierResult>("/email-verifier", { email });

    if (!data) {
      return {
        content: [{ type: "text", text: `Could not verify email: ${email}. Try again later.` }]
      };
    }

    // Build a clear status message
    let statusMessage: string;
    switch (data.result) {
      case "deliverable":
        statusMessage = "VALID - This email should receive messages";
        break;
      case "undeliverable":
        statusMessage = "INVALID - This email will bounce";
        break;
      case "risky":
        statusMessage = "RISKY - May or may not deliver (accept-all server or catch-all)";
        break;
      default:
        statusMessage = "UNKNOWN - Could not determine deliverability";
    }

    // Build details
    const checks = [
      `Format Valid: ${data.regexp ? "Yes" : "No"}`,
      `MX Records: ${data.mx_records ? "Found" : "Missing"}`,
      `SMTP Server: ${data.smtp_server ? "Responding" : "Not responding"}`,
      `SMTP Check: ${data.smtp_check ? "Passed" : "Failed"}`,
      `Gibberish: ${data.gibberish ? "Yes (suspicious)" : "No"}`,
      `Disposable: ${data.disposable ? "Yes (temporary email)" : "No"}`,
      `Webmail: ${data.webmail ? "Yes (Gmail, Yahoo, etc.)" : "No (company email)"}`,
      `Accept-All: ${data.accept_all ? "Yes (can't fully verify)" : "No"}`
    ];

    const result = `
Email: ${data.email}

Status: ${statusMessage}
Score: ${data.score}/100

Verification Details:
${checks.map(c => "- " + c).join("\n")}

Recommendation: ${
  data.result === "deliverable" ? "Safe to send" :
  data.result === "undeliverable" ? "Do NOT send - will bounce" :
  data.result === "risky" ? "Send with caution - monitor bounces" :
  "Verify manually before sending"
}
    `.trim();

    return {
      content: [{ type: "text", text: result }]
    };
  }
);

// Start the server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Hunter.io MCP Server running");
}

main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const HUNTER_API_BASE = "https://api.hunter.io/v2";
const API_KEY = process.env.HUNTER_API_KEY;

if (!API_KEY) {
  console.error("HUNTER_API_KEY environment variable is required");
  process.exit(1);
}

const server = new McpServer({ name: "hunter", version: "1.0.0" });

// Types
interface DomainSearchResult {
  domain: string;
  organization: string | null;
  pattern: string | null;
  accept_all: boolean;
  emails: Array<{
    value: string;
    confidence: number;
    first_name: string | null;
    last_name: string | null;
    position: string | null;
    department: string | null;
    linkedin: string | null;
    phone_number: string | null;
  }>;
}

interface EmailFinderResult {
  first_name: string;
  last_name: string;
  email: string;
  score: number;
  domain: string;
  position: string | null;
  linkedin_url: string | null;
}

interface EmailVerifierResult {
  email: string;
  result: "deliverable" | "undeliverable" | "risky" | "unknown";
  score: number;
  regexp: boolean;
  gibberish: boolean;
  disposable: boolean;
  webmail: boolean;
  mx_records: boolean;
  smtp_server: boolean;
  smtp_check: boolean;
  accept_all: boolean;
}

// API helper
async function hunterRequest<T>(endpoint: string, params: Record<string, string> = {}): Promise<T | null> {
  const url = new URL(`${HUNTER_API_BASE}${endpoint}`);
  url.searchParams.set("api_key", API_KEY!);
  for (const [key, value] of Object.entries(params)) {
    url.searchParams.set(key, value);
  }

  try {
    const response = await fetch(url.toString());
    if (!response.ok) return null;
    const result = await response.json();
    return result.data as T;
  } catch {
    return null;
  }
}

// Tool 1: Domain Search
server.tool(
  "domain_search",
  "Find email addresses at a company domain",
  {
    domain: z.string().describe("Company domain (e.g., stripe.com)"),
    limit: z.number().optional().default(10).describe("Max results (default 10)")
  },
  async ({ domain, limit }) => {
    const data = await hunterRequest<DomainSearchResult>("/domain-search", {
      domain,
      limit: String(Math.min(limit, 100))
    });

    if (!data || data.emails.length === 0) {
      return { content: [{ type: "text", text: `No emails found for ${domain}` }] };
    }

    const emails = data.emails.map(e => {
      const name = [e.first_name, e.last_name].filter(Boolean).join(" ") || "Unknown";
      return `- ${e.value} | ${name} | ${e.position || "Unknown role"} | ${e.confidence}% confidence`;
    }).join("\n");

    return {
      content: [{
        type: "text",
        text: `Found ${data.emails.length} emails at ${data.domain}:\n\n${emails}`
      }]
    };
  }
);

// Tool 2: Email Finder
server.tool(
  "email_finder",
  "Find a specific person's email at a company",
  {
    domain: z.string().describe("Company domain"),
    first_name: z.string().describe("First name"),
    last_name: z.string().describe("Last name")
  },
  async ({ domain, first_name, last_name }) => {
    const data = await hunterRequest<EmailFinderResult>("/email-finder", {
      domain, first_name, last_name
    });

    if (!data?.email) {
      return { content: [{ type: "text", text: `No email found for ${first_name} ${last_name} at ${domain}` }] };
    }

    return {
      content: [{
        type: "text",
        text: `Found: ${data.email}\nConfidence: ${data.score}%\nPosition: ${data.position || "Unknown"}`
      }]
    };
  }
);

// Tool 3: Email Verifier
server.tool(
  "email_verifier",
  "Verify if an email address is valid and deliverable",
  {
    email: z.string().email().describe("Email to verify")
  },
  async ({ email }) => {
    const data = await hunterRequest<EmailVerifierResult>("/email-verifier", { email });

    if (!data) {
      return { content: [{ type: "text", text: `Could not verify: ${email}` }] };
    }

    const status = data.result === "deliverable" ? "VALID" :
                   data.result === "undeliverable" ? "INVALID" :
                   data.result === "risky" ? "RISKY" : "UNKNOWN";

    return {
      content: [{
        type: "text",
        text: `${email}: ${status} (Score: ${data.score}/100)\nDisposable: ${data.disposable ? "Yes" : "No"}\nWebmail: ${data.webmail ? "Yes" : "No"}`
      }]
    };
  }
);

// Start server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Hunter MCP Server running");
}

main().catch(console.error);

npm run build

HUNTER_API_KEY=your-key-here npx @modelcontextprotocol/inspector node build/index.js

claude mcp add hunter --env HUNTER_API_KEY=your-key-here -- node /ABSOLUTE/PATH/TO/hunter-mcp/build/index.js

const API_KEY = process.env.MY_API_KEY;

if (!API_KEY) {
  console.error("MY_API_KEY environment variable is required");
  process.exit(1);
}

async function makeRequest(url: string) {
  const response = await fetch(url, {
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    }
  });
  return response.json();
}

claude mcp add myserver --env MY_API_KEY=your-key -- node /path/to/build/index.js

let lastRequestTime = 0;
const MIN_INTERVAL = 1000; // 1 second

async function rateLimitedFetch(url: string) {
  const elapsed = Date.now() - lastRequestTime;
  if (elapsed < MIN_INTERVAL) {
    await new Promise(r => setTimeout(r, MIN_INTERVAL - elapsed));
  }
  lastRequestTime = Date.now();
  return fetch(url);
}

if (!data) {
  return {
    content: [{
      type: "text",
      text: `Error: Could not fetch data.

Possible causes:
- Invalid API key
- Rate limit exceeded
- Network issue

Try again in a few seconds.`
    }]
  };
}