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