Harmonic MCP Server

MCP (Model Context Protocol) server for the Harmonic AI API - company and person enrichment for VC deal flow.

Features

This MCP server provides 13 tools for interacting with Harmonic's API:

Search Tools

• harmonic_search_companies - Natural language search for companies (e.g., "AI startups in San Francisco")
• harmonic_search_typeahead - Quick autocomplete search by company name or domain
• harmonic_find_similar_companies - Find companies similar to a given company

Company Tools

• harmonic_lookup_company - Look up company by domain, LinkedIn URL, or other identifiers
• harmonic_get_company - Get full company details by ID
• harmonic_get_company_employees - Get employees with filtering (founders, executives, etc.)
• harmonic_get_company_connections - Find team network connections to a company

Person Tools

• harmonic_lookup_person - Look up person by LinkedIn URL
• harmonic_get_person - Get full person details by ID

Saved Search Tools

• harmonic_list_saved_searches - List all saved searches/views
• harmonic_get_saved_search_results - Get results from a saved search
• harmonic_get_saved_search_net_new_results - Get only new results since last check (for deal flow monitoring)
• harmonic_clear_saved_search_net_new - Mark net new results as "seen"

Installation

No installation required when using npx (see Usage below).

Optional: Global Install

npm install -g @alludium/harmonic-mcp-server

Optional: From Source

git clone https://github.com/alludium/harmonic-mcp-server.git
cd harmonic-mcp-server
npm install
npm run build

Configuration

Set your Harmonic API key as an environment variable:

export HARMONIC_API_KEY=your_api_key_here

When using with Claude Desktop or Claude Code, set the key in the MCP server configuration's env block (see Usage section below).

Usage

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "harmonic": {
      "command": "npx",
      "args": ["-y", "@alludium/harmonic-mcp-server"],
      "env": {
        "HARMONIC_API_KEY": "your_api_key_here"
      }
    }
  }
}

With Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "harmonic": {
      "command": "npx",
      "args": ["-y", "@alludium/harmonic-mcp-server"],
      "env": {
        "HARMONIC_API_KEY": "your_api_key_here"
      }
    }
  }
}

Development Mode

# Run with tsx for development
HARMONIC_API_KEY=your_key npm run dev

API Coverage

Based on the Harmonic API documentation, this MCP covers:

Endpoint	Tool	Type
GET /search/search_agent	harmonic_search_companies	Entry point
GET /search/typeahead	harmonic_search_typeahead	Entry point
GET /search/similar_companies/{id}	harmonic_find_similar_companies	Discovery
POST /companies	harmonic_lookup_company	Entry point
GET /companies/{id}	harmonic_get_company	Detail
GET /companies/{id}/employees	harmonic_get_company_employees	Detail
GET /companies/{id}/userConnections	harmonic_get_company_connections	Detail
POST /persons	harmonic_lookup_person	Entry point
GET /persons/{id}	harmonic_get_person	Detail
GET /savedSearches	harmonic_list_saved_searches	Entry point
GET /savedSearches:results/{id}	harmonic_get_saved_search_results	Detail
GET /savedSearches:netNewResults/{id}	harmonic_get_saved_search_net_new_results	Monitoring
POST /savedSearches:clearNetNew/{id}	harmonic_clear_saved_search_net_new	Monitoring

Response Formats

All tools support two response formats:

• json (default): Structured data for programmatic use
• markdown: Human-readable formatted output

Use the response_format parameter to switch between formats.

Rate Limiting

The Harmonic API has a rate limit of 10 requests per second. This MCP server implements automatic throttling and retry logic for rate-limited requests.

Error Handling

The server provides clear, actionable error messages:

• 400: Bad request with parameter guidance
• 401: Authentication failure with API key setup instructions
• 404: Resource not found with alternative lookup suggestions
• 429: Rate limit exceeded with retry guidance
• 5xx: Server errors with wait/retry suggestions

Example Workflows

Find and Research a Company

1. harmonic_lookup_company { website_domain: "stripe.com" }
2. harmonic_get_company_employees { company_id: "142540", employee_group_type: "FOUNDERS_AND_CEO" }
3. harmonic_get_person { person_id: "person_id_from_step_2" }

Find Similar Companies

1. harmonic_search_companies { query: "fintech payment processing" }
2. harmonic_find_similar_companies { company_id: "id_from_step_1", size: 10 }
3. harmonic_get_company { company_id: "each_similar_company_id" }

Monitor Deal Flow

1. harmonic_list_saved_searches {}
2. harmonic_get_saved_search_results { search_id: "search_id_from_step_1", size: 50 }

License

MIT