README.md
Company and person enrichment for VC deal flow.
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
Tools (13)
harmonic_search_companiesNatural language search for companiesharmonic_search_typeaheadQuick autocomplete search by company name or domainharmonic_find_similar_companiesFind companies similar to a given companyharmonic_lookup_companyLook up company by domain, LinkedIn URL, or other identifiersharmonic_get_companyGet full company details by IDharmonic_get_company_employeesGet employees with filteringharmonic_get_company_connectionsFind team network connections to a companyharmonic_lookup_personLook up person by LinkedIn URLharmonic_get_personGet full person details by IDharmonic_list_saved_searchesList all saved searches/viewsharmonic_get_saved_search_resultsGet results from a saved searchharmonic_get_saved_search_net_new_resultsGet only new results since last checkharmonic_clear_saved_search_net_newMark net new results as seenEnvironment Variables
HARMONIC_API_KEYrequiredAPI key for accessing the Harmonic AI serviceConfiguration
claude_desktop_config.json
{"mcpServers": {"harmonic": {"command": "npx", "args": ["-y", "@alludium/harmonic-mcp-server"], "env": {"HARMONIC_API_KEY": "your_api_key_here"}}}}Try it
→Search for AI startups in San Francisco and give me a list of their founders.
→Find companies similar to Stripe and provide their company IDs.
→Get the latest new results from my saved search for fintech companies.
→Look up the company details for openai.com and list their executive team.