# Harmonic MCP Server
MCP (Model Context Protocol) server for the [Harmonic AI API](https://harmonic.ai) - 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
```bash
npm install -g @alludium/harmonic-mcp-server
```
### Optional: From Source
```bash
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:
```bash
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`):
```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:
```json
{
"mcpServers": {
"harmonic": {
"command": "npx",
"args": ["-y", "@alludium/harmonic-mcp-server"],
"env": {
"HARMONIC_API_KEY": "your_api_key_here"
}
}
}
}
```
### Development Mode
```bash
# Run with tsx for development
HARMONIC_API_KEY=your_key npm run dev
```
## API Coverage
Based on the [Harmonic API documentation](https://api.harmonic.ai), 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
