# 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