Connects Claude to the Ashby ATS to manage the hiring pipeline.
Ashby MCP Server
A Model Context Protocol (MCP) server that connects Claude to your Ashby ATS. Browse jobs, manage candidates, track applications through your hiring pipeline, and more — all through natural conversation.
Prerequisites
- Python 3.10+
- uv — a fast Python package manager
- An Ashby API key with
candidatesRead,jobsRead, andcandidatesWritepermissions- Generate one at https://app.ashbyhq.com/admin/api/keys
Setup
1. Install uv
If you don't already have uv installed:
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# macOS via Homebrew
brew install uv
After installing, find the absolute path to the uvx command (you'll need this for the config):
which uvx
This will return something like /Users/yourname/.local/bin/uvx. Keep this path handy.
2. Get your Ashby API key
Go to https://app.ashbyhq.com/admin/api/keys and create a new API key. Make sure it has at least:
candidatesReadjobsReadcandidatesWrite(if you want to create candidates, add notes, or move applications)
3. Configure Claude Desktop
Open your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add the following to the mcpServers section, replacing the placeholders with your actual values:
{
"mcpServers": {
"ashby": {
"command": "/absolute/path/to/uvx",
"args": [
"--from", "git+https://github.com/PlenishAI/mcp-ashby.git",
"ashby"
],
"env": {
"ASHBY_API_KEY": "your-ashby-api-key"
}
}
}
}
Important: Replace
/absolute/path/to/uvxwith the output fromwhich uvx(e.g./Users/yourname/.local/bin/uvx). Claude Desktop does not inherit your shell's PATH, so the full path is required.
4. Restart Claude Desktop
Quit and reopen Claude Desktop. The Ashby server should connect automatically. You can verify by asking Claude something like "list my open jobs in Ashby."
Alternative: Local Clone Setup
If the git+ URL method doesn't work (e.g. private repo or network restrictions), you can clone the repo locally:
git clone https://github.com/PlenishAi/mcp-ashby.git ~/projects/mcp-ashby
Then use uv (not uvx) in your config, pointing to the local directory:
{
"mcpServers": {
"ashby": {
"command": "/absolute/path/to/uv",
"args": [
"--directory", "/absolute/path/to/mcp-ashby",
"run", "ashby"
],
"env": {
"ASHBY_API_KEY": "your-ashby-api-key"
}
}
}
}
Note: When using a local clone, run
which uvto get the path — the command isuv, notuvx.
To update, just git pull from the repo directory.
Available Tools
Jobs
| Tool | Description |
|---|---|
job_list |
List all jobs with optional status filter (Draft, Open, Closed, Archived) |
job_info |
Get details of a single job by ID |
job_search |
Search jobs by title |
Candidates
| Tool | Description |
|---|---|
candidate_list |
List all candidates with cursor pagination |
candidate_search |
Search candidates by email and/or name |
candidate_info |
Get full details of a candidate by ID |
candidate_create |
Create a new candidate |
candidate_create_note |
Add an HTML-formatted note to a candidate |
candidate_list_notes |
List all notes for a candidate |
candidate_add_tag |
Add a tag to a candidate |
candidate_tag_list |
List all available candidate tags |
Applications
| Tool | Description |
|---|---|
application_list |
List applications with optional jobId, status, and date filters |
application_info |
Get full details of an application by ID |
application_create |
Create an application linking a candidate to a job |
application_change_stage |
Move an application to a different interview stage |
Interviews & Pipeline
| Tool | Description |
|---|---|
interview_stage_list |
List interview stages for a given interview plan |
interview_plan_list |
List all interview plans |
interview_list |
List all interviews with cursor pagination |
interview_info |
Get details of a single interview by ID |
Reference Data
| Tool | Description |
|---|---|
department_list |
List all departments |
user_list |
List all users (team members) |
source_list |
List all candidate sources |
archive_reason_list |
List all archive reasons |
location_list |
List all locations |
Troubleshooting
"No such file or directory" on startup
Claude Desktop can't find uvx. Make sure you're using the full absolute path from which uvx in your config, not just "uvx".
"Package not found in registry"
If you see a PyPI resolution error, make sure the --from argument uses the `git
Tools (24)
job_listList all jobs with optional status filter.job_infoGet details of a single job by ID.job_searchSearch jobs by title.candidate_listList all candidates with cursor pagination.candidate_searchSearch candidates by email and/or name.candidate_infoGet full details of a candidate by ID.candidate_createCreate a new candidate.candidate_create_noteAdd an HTML-formatted note to a candidate.candidate_list_notesList all notes for a candidate.candidate_add_tagAdd a tag to a candidate.candidate_tag_listList all available candidate tags.application_listList applications with optional jobId, status, and date filters.application_infoGet full details of an application by ID.application_createCreate an application linking a candidate to a job.application_change_stageMove an application to a different interview stage.interview_stage_listList interview stages for a given interview plan.interview_plan_listList all interview plans.interview_listList all interviews with cursor pagination.interview_infoGet details of a single interview by ID.department_listList all departments.user_listList all users (team members).source_listList all candidate sources.archive_reason_listList all archive reasons.location_listList all locations.Environment Variables
ASHBY_API_KEYrequiredAPI key generated from Ashby admin settings with candidatesRead, jobsRead, and candidatesWrite permissions.Configuration
{"mcpServers": {"ashby": {"command": "/absolute/path/to/uvx", "args": ["--from", "git+https://github.com/PlenishAI/mcp-ashby.git", "ashby"], "env": {"ASHBY_API_KEY": "your-ashby-api-key"}}}}