Homerun MCP Server

Move, tag, email and disqualify candidates; close jobs, from your agent.

託管 MCP 伺服器

npx add-mcp 'https://cotlet.dev/mcp/v1/homerun'

可安裝到 Claude Code、Codex、Cursor 等客戶端

文件

Cotlet · Integrations · How it works · Security · For developers · For automation agencies · Blog · API docs · Help center · Changelog · Contact · Pricing · Sign up

Homerun API and MCP server: Let your AI agent clear the Homerun pipeline.

Homerun has no MCP server (checked 27 Oct 2026). Its Public API, version 2, reads jobs and manages applications, notes and tags, at 60 requests a minute. The pricing table ticks it on Plus only (€249 a month billed yearly), an admin makes the key, and trials get none. Cotlet runs 14 Homerun tools hosted, over MCP for agents and REST for scripts, on Light, Basic or Plus.

Move, tag, email and disqualify candidates; close jobs, from your agent. Use it in ChatGPT, Claude or any AI agent over MCP, or in n8n, Make and scripts over REST.

MCP setup REST API guide

Cotlet is an independent service. It is not affiliated with, endorsed by or sponsored by Homerun. Homerun is a trademark of its owner. If Homerun's own integrations cover what you need, use them first.

What can you automate in Homerun?

  • Disqualify misfits with the right reason
  • Answer overdue first replies
  • Close a job at 50 candidates
  • Log interview notes and tags
  • Count candidates per stage each Monday
  • Move a candidate to a better job

Does Homerun have an MCP server or an API?

  • Jobs are read only in the API: it cannot create, edit, close or hide a job.
  • It returns why a candidate was disqualified but has no call to disqualify one. The only email it sends is the application confirmation, once.
  • Homerun has no Zapier app or n8n node (both pages answer 404), and its help center says it does not support setups built on the API.
What you needPublic API (Plus)GitHub MCP serversCotlet
Read jobs and applicationsYesYes, with a Plus keyYes
Move stage, notes and tagsYesMoves and notesYes
Disqualify with a reasonNoNoYes, after your OK
Email a candidateConfirmation email onlyGmail or Outlook draftsThrough Homerun, after your OK
Close or hide a jobNoNoYes, after your OK
Plan you needPlus, €249 a month and upPlusLight, Basic or Plus

Checked 27 Oct 2026. Sources: Homerun Public API documentation, What can you do with the Homerun Public API? (Homerun Help), Homerun pricing, Compare plans, Homerun AI info

How does Cotlet connect to Homerun?

  1. Sign in to Homerun. Use your own account in its Cotlet Cloud Browser.
  2. Choose MCP or REST. Connect your agent or create a Cotlet API key.
  3. Run your workflow. Ask your agent or send an HTTP request.

We never keep your Homerun password, and no disqualification, candidate email, job move or closed job is saved before you approve it.

Connect Homerun to your agent or workflow

Use MCP with your AI agent, or HTTP requests in n8n, Make, Zapier and scripts. Follow the MCP setup below or jump to the REST guide.

  1. Open Homerun in a Cloud Browser. Make a Cotlet account, open Homerun in its Cloud Browser, log in as the recruiter or admin who runs hiring, and press Enable for agents.
  2. Add the Cotlet address. Paste https://cotlet.dev/mcp/v1 where your agent lists MCP servers or connectors.
  3. Approve the connection. Chat apps show a Cotlet sign-in page. Code editors, n8n and scripts send an API key from the console.

https://cotlet.dev/mcp/v1 serves every app you enable on Cotlet, Homerun included. Enable Homerun after connecting and the agent needs a refresh of the connector to list its tools.

Claude:

Settings > Connectors > Add custom connector
URL: https://cotlet.dev/mcp/v1/connect

Claude Code:
claude mcp add --transport http cotlet \
  https://cotlet.dev/mcp/v1 \
  --header "Authorization: Bearer $COTLET_API_KEY"

ChatGPT:

Settings > Apps & Connectors > Create
MCP server URL: https://cotlet.dev/mcp/v1/connect
Authentication: OAuth

Cursor:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "cotlet": {
      "url": "https://cotlet.dev/mcp/v1",
      "headers": { "Authorization": "Bearer ${env:COTLET_API_KEY}" }
    }
  }
}

Codex:

# ~/.codex/config.toml
[mcp_servers.cotlet]
url = "https://cotlet.dev/mcp/v1"
bearer_token_env_var = "COTLET_API_KEY"

n8n:

MCP Client Tool (inside an AI Agent)
Transport: HTTP Streamable
URL: https://cotlet.dev/mcp/v1
Auth: Bearer, <your key>
Tool: homerun_read

Make, Zapier:

Make: MCP Client > Call a tool
Zapier: MCP Client by Zapier > Run Tool
Server URL: https://cotlet.dev/mcp/v1
Token: <your key>
Tool: homerun_write

How to use the Homerun REST API

Create your Cotlet API key

Create a Cotlet API key with access to Homerun and its read operations. Store it as COTLET_API_KEY in your environment or automation platform's credential store.

Connect Homerun in Cotlet and enable it for agents. Account access: Your own Homerun account. What your agent can do follows your permissions in Homerun, and a key from an admin is not needed.

Make your first Homerun API request

REST:

curl https://cotlet.dev/api/v1/homerun/jobs \
  -H "Authorization: Bearer $COTLET_API_KEY"

Read jobs and apply the operation limits

A successful REST call puts the tool output in result. This illustrative response excerpt omits call IDs, messages and credit details.

Illustrative response excerpt:

{
  "status": "success",
  "app": "homerun",
  "tool": "list_jobs",
  "result": {
    "jobs": [
      {
        "job_id": "job_3b7e91",
        "title": "Customer Success Manager",
        "state": "active",
        "visibility": "public"
      },
      {
        "job_id": "job_9d4a27",
        "title": "Product Designer",
        "state": "active",
        "visibility": "public"
      },
      {
        "job_id": "job_c51f08",
        "title": "Office Manager",
        "state": "active",
        "visibility": "private"
      }
    ]
  }
}

Returns each job with its ID, title, state and visibility, in the order of the Jobs page. Draft jobs are visible only to the hiring team, which includes the account the agent uses.

Use the ID in every other call.

Keep the same selection when continuing a list. Compare changed record values as well as identifiers when refreshing your destination.

Homerun workflows for agents and automations

ToolConnect throughExample workflow
n8nHTTP RequestRead one job: its hiring stages, closing date and application form questions. Use get_job in your configured team report.
MakeHTTP > Make a requestList the candidates of one job, filtered by stage, tag or status. Use list_candidates in your configured team report.
Python or Node.jsREST APIList the tags your company uses on candidates. Use list_tags in your configured team report.

Send Authorization: Bearer <your Cotlet API key> in request headers. You configure the schedule, destination and record comparisons.

Cotlet reads Homerun; your workflow steps write to your chosen destination. These HTTP workflows do not require a native Cotlet connector or a prebuilt template.

Python and Node.js can use the same HTTP requests without an AI agent. Keep access keys in credentials, outside shared workflow exports.

The API and MCP reference lists operations and inputs. The REST API guide explains authentication, errors and approvals.

Homerun API endpoints and MCP tools

Candidates and stages

A candidate is one application to one job, so a person who applied twice has two IDs. A stage can send an automatic email when someone enters it.

  • List candidates (list_candidates, read): List the candidates of one job, filtered by stage, tag or status.
  • Get a candidate (get_candidate, read): Read a candidate profile with answers, ratings, notes and messages.
  • Move a candidate to a stage (move_candidate_to_stage, write, asks first): Move a candidate to another hiring stage of the same job.
  • Move a candidate to another job (move_candidate_to_job, write, asks first): Move a candidate to another job.

Disqualify and email

The reason stays inside Homerun; the candidate hears only what an email says, and only if you choose to send one.

  • List disqualification reasons (list_disqualification_reasons, read): List the reasons you can give when disqualifying a candidate.
  • Disqualify a candidate (disqualify_candidate, write, asks first): Disqualify a candidate with a reason and choose whether to tell them.
  • Email a candidate (send_candidate_email, write, asks first): Send an email to one candidate through Homerun.

Notes and tags

Internal to the hiring team. A new tag name is added for the whole company, so the agent reuses names from list_tags.

  • List tags (list_tags, read): List the tags your company uses on candidates.
  • Add a note to a candidate (add_candidate_note, write): Add an internal note to a candidate profile.
  • Tag a candidate (add_candidate_tag, write): Add a tag to a candidate, creating the tag if it does not exist.
  • Remove a tag from a candidate (remove_candidate_tag, write): Remove a tag from a candidate.

Jobs

Writing and publishing a job post stays in Homerun. Visibility changes only on active jobs.

  • List jobs (list_jobs, read): List your jobs with their state and visibility.
  • Get a job (get_job, read): Read one job: its hiring stages, closing date and application form questions.
  • Set job visibility (set_job_visibility, write, asks first): Make an active job public, private or closed.

Inputs, REST path and example response of every tool: https://cotlet.dev/integrations/homerun-api-mcp-server#tools

Who can see my Homerun session, and how do I revoke it?

  • What we store. Your logged-in Homerun profile, AES-256-GCM encrypted, in Finland. No password.
  • What your agent gets. 14 Homerun tools, never the session cookie.
  • What the session sees. The jobs and candidates your Homerun user can open, no more.
  • What no tool touches. Job post text, Homerun HR employee records, billing and settings.
  • If Homerun logs you out. You get an email with a link and log in again yourself.
  • How to cut access. Disable for agents, reset the browser or delete the key.

Applications hold CVs, answers and your team's ratings, which is personal data under the GDPR. Homerun is a Dutch company and Cotlet a Polish one, and our DPA covers business accounts. Give the agent a login that already sees the jobs it works on. The Cotlet site has A+ on Qualys SSL Labs, securityheaders.com and Mozilla Observatory (live results).

Approvals, undo and mistakes

  1. Reads the stage. Active candidates in Application, so nobody already disqualified is judged twice.
  2. Quotes the answer. Each pick names the application answer it relied on and a reason from your list.
  3. Waits for your OK. Every disqualification waits in your Cotlet console, marked with or without an email.
  4. Leaves the unclear. Empty or mixed answers stay in the stage with a one-line note for you.
ActionUndo
Disqualify a candidateRe-qualify in Homerun; they return to their old stage. An email sent with it stays sent
Email a candidateNone; write a correction
Move to another stageMove back; a stage email may already have gone out
Move to another jobMove back; stage reviews, scorecards and stage history of the old job are gone
Close or hide a jobSet it to public again
Note or tagRemove the tag; a note stays unless you delete it in Homerun

5 of the 8 write tools ask first. add_candidate_note, add_candidate_tag and remove_candidate_tag run at once, because the hiring team sees them and the candidate never does. Reads run at once. For a scheduled run you can switch the wait off per tool.

Disqualified candidates drop out of the Kanban view and show only in Table view. The agent lists every one it disqualified, so a wrong pick is easy to find.

MCP call:

{
  "name": "move_candidate_to_stage",
  "arguments": {
    "job_id": "job_3b7e91",
    "candidate_id": "ap_K2mP7rS1uW5yA9bC3dE6",
    "stage": "Phone call"
  }
}

REST:

curl -X POST https://cotlet.dev/api/v1/homerun/jobs/job_3b7e91/candidates/ap_K2mP7rS1uW5yA9bC3dE6/to-stage/move \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage":"Phone call"}'

Response:

{
  "candidate_id": "ap_K2mP7rS1uW5yA9bC3dE6",
  "status": "moved",
  "from_stage": "Application",
  "to_stage": "Phone call"
}

A nightly script or your own hiring dashboard can call the same tools over REST at /api/v1/homerun, with one key and one price, and no Plus plan. A call your Homerun user may not make returns an error and costs nothing. Each tool row above shows its REST path.

How much does the Homerun MCP server cost?

About $44 a month for a 60-person company with 3 open jobs, 7,600 credits. Works on Homerun Light (€89 a month billed yearly); the Public API alone needs Plus at €249.

JobCallsCredits
Screen new applicants in 3 jobs, each workday15 × 223,300
Personal reply to an overdue applicant, with a note3 × 401,200
Interview notes and a shortlist tag3 × 12360
Close a job that reached its limit, daily check4 × 22880
Pipeline report by stage, weekly7 × 4280
Move candidates to a better-fitting job4 × 280
Cloud Browser, 30 days1,500
Total7,600
  • Free 7-day trial, no card
  • 10 credits per successful call, MCP or REST
  • 50 credits a day for the Cloud Browser
  • No Plus plan or admin API key needed

The month is our example: 3 open jobs and about 150 applications, 40 overdue first replies and 12 interviews. Homerun says it is built for companies of 20 to 200 people and Light has 3 job slots; it publishes no applicant counts. Dollars at the $29 pack rate.

Homerun MCP server on GitHub or hosted: which to use

OptionWhat it doesWhere it stops
MrMendiola/homerun-mcp15 tools on the Public API: pipeline reports to Excel, bulk moves and notes, add or delete candidates. MIT, 0 stars, first commit 20 Oct 2026.Plus key; replies land as Gmail or Outlook drafts, not in Homerun; no disqualify or job changes.
softcery/homerun-ats-mcp5 tools: read jobs and applications, add a note. No license, last commit 18 Feb 2026.Plus key; no moves, tags or emails; no auth of its own.
usefulapi Homerun MCPHosted, 7 reads plus move to stage and add note. 50 calls a month free, then $9.Asks for your Homerun API key, so Plus; notes cannot be removed.
StackOneManaged MCP with 11 actions on applications, vacancies, notes and files.Same API and key; no disqualify, email or job changes; price on request.

If you are on Plus and only need reports, moves and notes, a server on the Public API does it. If your agent should disqualify, reply through Homerun or close a full job, or you are on Light or Basic, Cotlet does that hosted.

Also listed on: Odel, mcpbeat

Who runs Cotlet

Take Group sp. z o.o. runs Cotlet: a software company registered in Poland, EU (VAT PL6342984273), in business since 2019. The founders are Bart Krawczyk (Co-founder, CTO) and Jake Slugocki (Co-founder, SEO, sales and marketing). Questions about the Homerun tools go to contact@cotlet.dev.

Homerun API and MCP: questions

How do I get access?

Sign up free at https://cotlet.dev, open Homerun under Integrations in the console and log in to Homerun in its Cloud Browser. The trial starts when you sign up and needs no card.

How do I connect Homerun to ChatGPT or Claude?

Sign up at cotlet.dev, log in to Homerun once in its Cloud Browser and add Cotlet to ChatGPT or Claude, following the steps in your console. No API key is needed. ChatGPT and Claude then work in your Homerun account through Cotlet, in their phone apps too.

What can ChatGPT do in Homerun?

With Cotlet, ChatGPT, Claude and other AI agents handle jobs like these in Homerun: disqualify unqualified candidates in bulk; reply to new applicants on time; close jobs that have enough applicants. You ask in plain words, and anything that reaches other people waits for your OK first.

Do I need a paid Homerun plan or an API key?

No key. Homerun's own Public API is for paid plans only, trials are excluded, and only an admin can generate a key. Cotlet works in your own Homerun account instead, so what your agent can do follows your permissions in Homerun.

Can it create or edit a job post?

No. The tools read jobs and change their visibility between public, private and closed. Writing and publishing a job post stays in Homerun, as it does in the Public API, where jobs are read-only.

Does a candidate see why they were disqualified?

No. Homerun does not share the disqualification reason with the candidate. They hear only from an email, and disqualify_candidate sends one only when you set notify to email.

Does Homerun have webhooks?

No. The Public API documents none, and Homerun has no Zapier app. To react to new applications, run your agent on a schedule and read the stage.

Does it work with Homerun HR?

No. The tools cover hiring: jobs, candidates, notes, tags, emails and disqualifications. Employee records, leave and onboarding in Homerun HR are not touched.

Is the MCP server different from the REST API?

Only in how you call it. Both have the same 14 tools, inputs and answers, with one API key and one price. Agents use MCP; scripts use REST.

Is Cotlet affiliated with Homerun?

No. Cotlet is independent and not affiliated with Homerun B.V. It is also unrelated to Homerun Presales, a sales tool with the same name.

Can I use the Homerun API without an AI agent?

Yes. Call Cotlet's REST API from a script or an HTTP step in n8n, Make or Zapier with your Cotlet key. MCP is the alternative for AI agents; you do not need to connect an agent to use REST.


Give your AI agents your signed-in browser.

Product: Integrations · How it works · Pricing · Security

Resources: Blog · API docs · Help center · Changelog · GitHub

Solutions: For developers · For automation agencies

Company: About · AI info: company facts · Contact

Legal: Terms of service · Privacy policy · Refund policy · Acceptable use · Cookie policy · DPA · Subprocessors

Elsewhere: Status page · Cotlet on GitHub · Cotlet on X · Cotlet on LinkedIn · Cotlet on Product Hunt · Cotlet on Crunchbase · Cotlet on SaaSHub

Cotlet.dev is built by Bart Krawczyk and Jake Slugocki, the founders of Take Group sp. z o.o., ul. Wincentego Janasa 4, 40-855 Katowice, Poland. KRS 0000871398, NIP 6342984273, VAT EU: PL6342984273. About us

Cotlet is an independent service. It is not affiliated with, endorsed by or sponsored by any of the products listed on this site. Product names are trademarks of their respective owners.