# herohunt-mcp

MCP server for the [HeroHunt People Search API](https://www.herohunt.ai/people-search-api). Search for talent across LinkedIn, GitHub, and StackOverflow from any MCP-compatible AI agent.

## Quick Start

### Option 1: Remote URL (recommended)

Claude Desktop, Cursor, and most modern MCP clients support remote HTTP endpoints directly. No package installation needed.

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "herohunt-people-search": {
      "url": "https://api.herohunt.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "herohunt-people-search": {
      "url": "https://api.herohunt.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Option 2: stdio (via npx)

For MCP clients that only support stdio transport:

```json
{
  "mcpServers": {
    "herohunt-people-search": {
      "command": "npx",
      "args": ["-y", "herohunt-mcp"],
      "env": {
        "HEROHUNT_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

## Get Your API Key

Sign up at [herohunt.ai/app/api/sign-up](https://www.herohunt.ai/app/api/sign-up) to get your API key.

## Tools

| Tool | Type | Description |
|------|------|-------------|
| `people_search` | Write | Search for people profiles using natural language. 1 credit per reserved slot. |
| `people_search_paginate` | Read | Fetch more results for an existing search. Free unless enrichment is on. |
| `account_usage_get` | Read | Get plan, credits, rate limit info. Free. |
| `account_searches_list` | Read | List past searches. Free. |
| `account_upgrade_link` | Read | Get plan upgrade URL. Free. |
| `account_billing_portal_link` | Read | Get Stripe billing portal URL. Free. |
| `api_keys_list` | Read | List API key prefixes and scopes. Free. |
| `api_keys_create` | Write | Create a new API key. |
| `api_keys_rotate` | Write | Rotate an existing API key. |
| `api_keys_revoke` | Write | Permanently revoke an API key. |

## Example

After connecting, ask your AI agent:

> "Use HeroHunt to find me 5 senior Go engineers in Berlin and summarise the top 3."

The agent will call `people_search` with a natural language query, receive structured profile data (name, title, company, location, skills, platform links), and summarize the results.

To get contact info, ask:

> "Enrich the results with emails and phone numbers."

The agent will call `people_search_paginate` with `enrich: true`.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `HEROHUNT_API_KEY` | Yes | - | Your People Search API key |
| `HEROHUNT_MCP_URL` | No | `https://api.herohunt.ai/api/v1/mcp` | Override the MCP endpoint URL |

## Links

- [API Documentation](https://www.herohunt.ai/people-search-api)
- [Sign Up](https://www.herohunt.ai/app/api/sign-up)
- [Dashboard](https://www.herohunt.ai/app/api/dashboard)

## License

MIT