Homerun ATS MCP Server

Homerun ATS MCP Server

MCP server that connects AI agents to Homerun — an applicant tracking system. Enables AI-assisted candidate review: browse vacancies, inspect applications, and leave review notes.

Standalone server. No runtime dependency on the platform. Users add it like any remote MCP server.

Tools

| Tool | Description | | ------------------- | -------------------------------------------------------------------------------- | | list_vacancies | List job openings with optional status filter and pagination | | get_vacancy | Get full vacancy details (description, stages, location, department) | | list_applications | Search/filter applications by vacancy, stage, hired status, disqualification | | get_application | Get full application details (candidate profile, notes, files, question answers) | | add_note | Add a review note to an application |

Setup

Get a Homerun API key

Homerun App → Integrations → API Keys. Assign scopes:

• vacancies:read
• job-applications:read
• job-application-notes:read (for notes in get_application)
• job-application-notes:write (for add_note)

API access requires the Homerun Plus plan.

Run locally

pnpm -F @softcery/mcp-homerun dev

Starts on http://localhost:8080. The MCP endpoint is /mcp.

Environment variables

| Variable | Default | Description | | -------------------- | --------- | --------------------------------------------------------------------- | | PORT | 8080 | Server port | | HOST | 0.0.0.0 | Bind address | | SESSION_TIMEOUT_MS | 1800000 | Session expiry (30 min) | | ALLOWED_HOSTS | — | Comma-separated allowed Host header values (DNS rebinding protection) |

Connect

From the platform

Admin UI → Agent → Integrations → Add Server:

• URL: https://<deployed-host>/mcp
• API Key: your Homerun API key

From Claude Desktop

{
  "mcpServers": {
    "homerun": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <HOMERUN_API_KEY>"
      }
    }
  }
}

From any MCP client

Send an initialize request to POST /mcp with your Homerun API key as a Bearer token in the Authorization header. The server creates a stateful session — subsequent requests use the mcp-session-id header.

Auth model

No server-level auth. The Bearer token from the client's Authorization header is used directly as the Homerun API key. Each user's key has its own rate limit (60 req/min).

Development

pnpm -F @softcery/mcp-homerun test    # run tests
pnpm -F @softcery/mcp-homerun lint    # tsc + oxlint + knip
pnpm -F @softcery/mcp-homerun build   # production build

Docker

docker build -f mcp-servers/homerun/Dockerfile -t mcp-homerun .
docker run -p 8080:8080 mcp-homerun