Homerun MCP Server
Move, tag, email and disqualify candidates; close jobs, from your agent.
Máy chủ MCP được lưu trữ
npx add-mcp 'https://cotlet.dev/mcp/v1/homerun'Cài vào Claude Code, Codex, Cursor và nhiều công cụ khác
Tài liệu
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.
- Free 7-day trial, no card
- Unofficial, not affiliated with Homerun
- Page: https://cotlet.dev/integrations/homerun-api-mcp-server
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 need | Public API (Plus) | GitHub MCP servers | Cotlet |
|---|---|---|---|
| Read jobs and applications | Yes | Yes, with a Plus key | Yes |
| Move stage, notes and tags | Yes | Moves and notes | Yes |
| Disqualify with a reason | No | No | Yes, after your OK |
| Email a candidate | Confirmation email only | Gmail or Outlook drafts | Through Homerun, after your OK |
| Close or hide a job | No | No | Yes, after your OK |
| Plan you need | Plus, €249 a month and up | Plus | Light, 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?
- Sign in to Homerun. Use your own account in its Cotlet Cloud Browser.
- Choose MCP or REST. Connect your agent or create a Cotlet API key.
- 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.
- 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.
- Add the Cotlet address. Paste https://cotlet.dev/mcp/v1 where your agent lists MCP servers or connectors.
- 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
| Tool | Connect through | Example workflow |
|---|---|---|
| n8n | HTTP Request | Read one job: its hiring stages, closing date and application form questions. Use get_job in your configured team report. |
| Make | HTTP > Make a request | List the candidates of one job, filtered by stage, tag or status. Use list_candidates in your configured team report. |
| Python or Node.js | REST API | List 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
- Reads the stage. Active candidates in Application, so nobody already disqualified is judged twice.
- Quotes the answer. Each pick names the application answer it relied on and a reason from your list.
- Waits for your OK. Every disqualification waits in your Cotlet console, marked with or without an email.
- Leaves the unclear. Empty or mixed answers stay in the stage with a one-line note for you.
| Action | Undo |
|---|---|
| Disqualify a candidate | Re-qualify in Homerun; they return to their old stage. An email sent with it stays sent |
| Email a candidate | None; write a correction |
| Move to another stage | Move back; a stage email may already have gone out |
| Move to another job | Move back; stage reviews, scorecards and stage history of the old job are gone |
| Close or hide a job | Set it to public again |
| Note or tag | Remove 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.
| Job | Calls | Credits |
|---|---|---|
| Screen new applicants in 3 jobs, each workday | 15 × 22 | 3,300 |
| Personal reply to an overdue applicant, with a note | 3 × 40 | 1,200 |
| Interview notes and a shortlist tag | 3 × 12 | 360 |
| Close a job that reached its limit, daily check | 4 × 22 | 880 |
| Pipeline report by stage, weekly | 7 × 4 | 280 |
| Move candidates to a better-fitting job | 4 × 2 | 80 |
| Cloud Browser, 30 days | 1,500 | |
| Total | 7,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
| Option | What it does | Where it stops |
|---|---|---|
| MrMendiola/homerun-mcp | 15 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-mcp | 5 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 MCP | Hosted, 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. |
| StackOne | Managed 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.
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.