# homerun-mcp

Run your [Homerun](https://www.homerun.co) hiring from Claude.

Homerun is a great ATS, but day to day a lot of the work is manual: open each candidate, move them one by one through the stages, log in to reply to each of them, export numbers for the weekly update. This [MCP](https://modelcontextprotocol.io) server lets Claude (Desktop, Code, or any MCP client) do that work with you, for any role and any hiring process.

```
You:    How are our open roles doing? Who's been waiting more than 5 days?
Claude: 3 open vacancies, 47 active candidates. 6 have had no reply for 5+ days,
        4 of them in "New" for the Backend Engineer role. Report saved to
        ~/Documents/Homerun Reports/homerun-report-2026-10-20.xlsx

You:    Move the 4 in New to "Phone screen" and draft an invite for each.
Claude: [shows the 4 drafts] OK to create them as Gmail drafts and log a note in Homerun?
```

## What you can do

**See the pipeline**
- Funnel per vacancy and per stage, hired, disqualified, average rating
- Who has been waiting for a first reply for more than N days
- Time to first reply per vacancy

**Act in bulk**
- Move many candidates to a stage in one go, with an optional note on each
- Add notes to many candidates at once (screening summaries, "rejection sent on...")
- Add sourced candidates (from LinkedIn, events, referrals) without opening Homerun

**Reply to candidates**
- Claude drafts personal emails (rejection, next step, interview invite, status update) for a whole group
- You review them all in one list; with Gmail or Outlook connected they become drafts there
- Each candidate gets a note in Homerun so the team knows they were contacted

**Report on a schedule**
- One-call report to **Excel** (Summary, Needs reply, Active, All candidates), **CSV**, or **JSON**
- With a Google Drive connector, Claude can put it in **Google Sheets**
- Pair it with a scheduled task in Claude to get it every Monday, or every 2-3 days

## Tools

| Tool | What it does |
|---|---|
| `hiring_report` | Report across vacancies to xlsx / csv / json |
| `pipeline_summary` | Quick funnel for one vacancy |
| `list_vacancies`, `get_vacancy` | Openings, stages, candidate counts |
| `list_job_applications`, `get_job_application` | Candidates by vacancy, stage, hire date; notes and sources |
| `bulk_move_candidates` | Move many candidates to one stage (+ optional note) |
| `bulk_add_notes` | One note per candidate, many candidates |
| `move_candidate`, `add_note` | Same, one at a time |
| `create_candidate`, `update_candidate` | Add or edit candidates |
| `upload_candidate_file` | Attach a CV or assignment from your computer |
| `delete_candidate` | GDPR erasure, with confirmation |
| `homerun_ping` | Check the key |

**Prompts** (in Claude Desktop: the "+" menu > homerun):
- `hiring_review`: pipeline review + report + proposed next actions
- `reply_to_candidates`: drafts replies for a group of candidates, then logs them
- `candidate_brief`: one-page brief before an interview

## Install

### Claude Desktop (one click)

1. Download `homerun-mcp.mcpb` from [Releases](../../releases).
2. Double-click it (or Settings > Extensions > drag it in).
3. Paste your Homerun API key: Homerun > Settings > Integrations > API.

### Claude Code / other MCP clients

```bash
git clone https://github.com/MrMendiola/homerun-mcp && cd homerun-mcp
npm install && npm run build
claude mcp add homerun -e HOMERUN_API_KEY=your-key -- node "$PWD/dist/index.js"
```

Or in any `mcpServers` config:

```json
{
  "mcpServers": {
    "homerun": {
      "command": "node",
      "args": ["/absolute/path/to/homerun-mcp/dist/index.js"],
      "env": { "HOMERUN_API_KEY": "your-key" }
    }
  }
}
```

| Variable | Default | |
|---|---|---|
| `HOMERUN_API_KEY` | required | Bearer key from Homerun |
| `HOMERUN_REPORT_DIR` | `~/Documents/Homerun Reports` | Where reports are saved |
| `HOMERUN_NOTE_AUTHOR` | `Claude (AI assistant)` | Name on notes Claude writes |

## Scheduled reports

In Claude Desktop, create a scheduled task (weekly, or every 2-3 days) with a prompt like:

> Use the homerun hiring_review prompt with destination google_sheets and reply_sla_days 3.

Each run updates the report and gives you a short summary with proposed actions. Nothing is moved or sent without your OK.

## Good to know

- **Scoped keys.** For reports only, grant `vacancies:read` and `job-applications:read`. Add write scopes only if you want bulk moves and notes.
- **Humans decide.** Claude proposes, you approve. The server never rejects anyone on its own, and notes written by Claude are labelled. In the EU, AI that evaluates candidates is high-risk under the AI Act: keep a human in the loop.
- **Replies go through your email.** Homerun's public API has no endpoint to send messages, so replies are drafted in your email client (Gmail / Outlook connector) and logged in Homerun as a note. They will not show up in Homerun's own inbox.
- **Not in the API:** application form answers, assignment content, email threads, stage change dates.
- **Rate limit.** 60 requests/minute per key. The server throttles and retries automatically; a big bulk move may take a minute.
- **Local only.** Runs on your machine: candidate data goes from Homerun to you and Claude, no third-party middleware.
- **Unofficial.** Not affiliated with Homerun. Built on the public API v2.

## Develop

```bash
npm install
npm run build
npm run pack     # builds homerun-mcp.mcpb
```

See [docs/architecture.md](docs/architecture.md) for how it is put together.

## License

MIT