# ashby-mcp

MCP server for [Ashby](https://www.ashbyhq.com/) ATS — designed for candidate evaluation workflows.

This server exposes Ashby's recruiting data through the [Model Context Protocol](https://modelcontextprotocol.io/), letting AI agents review candidates, read application details, and write evaluation notes.

## Prerequisites

You need an Ashby API key:

1. Go to your Ashby admin settings → Integrations → API Keys
2. Create a new API key with these permissions:
   - `candidatesRead` — read candidate profiles, applications, notes, feedback
   - `jobsRead` — read job listings and details
   - `interviewsRead` — read interview stages and plans
   - `candidatesWrite` — add notes, tags, move application stages, archive applications
   - `hiringProcessMetadataRead` — list archive reasons and email templates

## Install

### Claude Code (recommended)

Run in your terminal:

```bash
claude mcp add ashby -e ASHBY_API_KEY=your-api-key-here -- npx -y ashby-mcp@latest
```

This auto-updates whenever a new version is published.

### Claude Desktop

Add this to your Claude Desktop MCP config (`Settings → Developer → Edit Config`):

```json
{
  "mcpServers": {
    "ashby": {
      "command": "npx",
      "args": ["-y", "ashby-mcp@latest"],
      "env": {
        "ASHBY_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

This also auto-updates on each restart.

> **Alternative:** You can download the [`.mcpb` bundle](https://github.com/dewierwan/ashby-mcp/releases/latest/download/ashby-mcp.mcpb) and double-click to install — no terminal needed. Note that this method pins you to a specific version and won't auto-update. You'll need to re-download after each release.

### Other MCP clients

Add the same JSON config above to your client's MCP server configuration.

### Docker

Build the image, then add it to your MCP client config:

```bash
docker build -t ashby-mcp .
```

```json
{
  "mcpServers": {
    "ashby": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "ASHBY_API_KEY", "ashby-mcp"],
      "env": {
        "ASHBY_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### From source

```bash
git clone https://github.com/dewierwan/ashby-mcp.git && cd ashby-mcp
npm install
npm run build
```

Then point your MCP client at `node dist/index.js` with the `ASHBY_API_KEY` environment variable set.

## Tools

All tools return dual-format responses: a human-readable summary followed by structured JSON.

### Jobs

#### `ashby_list_jobs`

List open jobs with IDs, titles, department, location, and status.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `status` | `"Open" \| "Closed" \| "Archived" \| "Draft" \| "All"` | `"Open"` | Filter by job status |
| `limit` | `number` (1-100) | `25` | Max results per page |
| `cursor` | `string` | — | Pagination cursor from previous response |

#### `ashby_get_job_details`

Full job details including description and interview plan stages.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | `string` | Yes | Job ID (UUID) |

#### `ashby_get_pipeline_summary`

Pipeline overview with candidate counts per stage, per job.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `job_id` | `string` | — | Summary for one job. Omit for all jobs. |
| `status` | `"Open" \| "Closed" \| "All"` | `"Open"` | Which jobs to include |

### Candidates

#### `ashby_get_candidate`

Comprehensive candidate profile with all applications resolved.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `candidate_id` | `string` | Yes | Candidate ID (UUID) |

#### `ashby_get_candidate_notes`

All notes on a candidate.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `candidate_id` | `string` | Yes | Candidate ID (UUID) |

#### `ashby_search_candidates`

Search candidates by name or email.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `string` | — | Candidate name to search for (required) |
| `email` | `string` | — | Optional email (AND logic with name) |
| `limit` | `number` (1-100) | `25` | Max results |

#### `ashby_add_candidate_note`

Add an evaluation note to a candidate. Visible to the hiring team.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `candidate_id` | `string` | Yes | Candidate ID (UUID) |
| `note` | `string` | Yes | Note content (plain text) |

#### `ashby_add_candidate_tag`

Tag a candidate (e.g. "Strong Hire", "Needs Review").

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `candidate_id` | `string` | Yes | Candidate ID (UUID) |
| `tag_id` | `string` | Yes | Tag ID (UUID) from Ashby admin settings |

#### `ashby_get_resume`

Download and extract text from a candidate's resume (PDF, text).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_handle` | `string` | Yes | File handle from candidate's `fileHandles` array |
| `file_name` | `string` | No | Original filename (helps determine format) |

### Applications

#### `ashby_list_candidates_for_job`

List candidates/applications for a specific job with stage and status.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `job_id` | `string` | — | Job ID (UUID) (required) |
| `limit` | `number` (1-100) | `25` | Max results per page |
| `cursor` | `string` | — | Pagination cursor |

#### `ashby_get_application_details`

Full application with stage history, feedback, and criteria evaluations.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `application_id` | `string` | Yes | Application ID (UUID) |

#### `ashby_get_application_form_submission`

Candidate's submitted application form responses (screening questions, cover letter, etc).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `application_id` | `string` | Yes | Application ID (UUID) |

#### `ashby_list_applications`

List applications across all jobs with date, status, stage, and source filters.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `created_after` | `string` (ISO datetime) | — | Only applications after this time |
| `created_before` | `string` (ISO datetime) | — | Only applications before this time |
| `job_id` | `string` | — | Filter to a specific job |
| `status` | `"Active" \| "Archived" \| "Hired" \| "Lead" \| "All"` | `"All"` | Filter by status |
| `stage_type` | `"Lead" \| "PreInterviewScreen" \| "Interview" \| "Offer" \| "All"` | — | Filter by stage type |
| `stage_name` | `string` | — | Filter by exact stage name |
| `source` | `string` | — | Filter by source (case-insensitive substring) |
| `limit` | `number` (1-100) | `25` | Max results |
| `cursor` | `string` | — | Pagination cursor |

#### `ashby_archive_application`

Archive an application with reason and optional rejection email.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `application_id` | `string` | — | Application ID (UUID) (required) |
| `archive_reason_id` | `string` | — | Reason ID from `ashby_list_archive_reasons` |
| `send_email` | `boolean` | `false` | Send rejection email (requires `email_template_id`) |
| `email_template_id` | `string` | — | Template ID from `ashby_list_email_templates` |

#### `ashby_bulk_archive`

Archive multiple applications at once (max 25).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `application_ids` | `string[]` (1-25) | — | Application IDs (required) |
| `archive_reason_id` | `string` | — | Reason ID, applied to all |
| `send_email` | `boolean` | `false` | Send rejection emails |
| `email_template_id` | `string` | — | Template ID for rejection emails |

### Interviews

#### `ashby_list_interview_stages`

List all interview stages across all interview plans. No parameters.

#### `ashby_list_upcoming_interviews`

List upcoming and pending interview schedules.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `start_after` | `string` (ISO datetime) | now | Only interviews after this time |
| `start_before` | `string` (ISO datetime) | — | Only interviews before this time |
| `status` | `"Scheduled" \| "NeedsScheduling" \| "Complete" \| "Cancelled" \| "All"` | `"All"` | Filter by status |
| `limit` | `number` (1-100) | `25` | Max results |

### Workflow

#### `ashby_move_application_stage`

Move an application to a different interview stage.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `application_id` | `string` | Yes | Application ID (UUID) |
| `stage_id` | `string` | Yes | Target stage ID from `ashby_list_interview_stages` |

#### `ashby_get_feedback`

Submitted feedback/scorecards for an application.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `application_id` | `string` | Yes | Application ID (UUID) |

#### `ashby_list_archive_reasons`

List available archive/rejection reasons. No parameters.

#### `ashby_list_email_templates`

List email templates for rejection emails. No parameters.

### Escape hatch

For anything the dedicated tools above don't cover (e.g. `offer.list`, `user.list`, `department.list`, `interviewPlan.list`, `candidate.update`), use the two generic tools below. They share the same auth, retries, and timeouts as every other tool.

#### `ashby_call_api`

Call any Ashby API endpoint directly. Returns the raw response envelope, including `success`, `results`, `moreDataAvailable`, and error details.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `endpoint` | `string` | Yes | Endpoint path, e.g. `"offer.list"`, `"user.list"`, `"candidate.update"`. No leading slash. |
| `params` | `object` | No | JSON body to POST. Defaults to `{}`. |

Marked `destructiveHint: true` so Claude surfaces the call before running it (a generic passthrough can hit write endpoints).

#### `ashby_get_api_docs`

Return a curated reference for the Ashby API: base URL, auth, response envelope, pagination, endpoint index grouped by resource, and common gotchas. No parameters.

Call this before `ashby_call_api` if you're not sure which endpoint or parameter names to use. Full official reference: <https://developers.ashbyhq.com/reference/>.

## Example Prompts

```
Show me all open engineering jobs.

List the candidates for the Senior Backend Engineer role and summarize where each one is in the pipeline.

Pull up the full profile for candidate Jane Smith — I want to see her resume info, application history, and any existing notes.

Review the feedback submitted for application abc-123 and summarize the interviewer evaluations.

Add a note to candidate xyz-456: "Strong technical skills demonstrated in system design round. Recommend advancing to final interview."

Move application abc-123 to the "Final Interview" stage.

Read the resume for candidate Jane Smith and summarize her experience.

How many people applied this week?

What does our pipeline look like for the Community Lead role?

Show me all candidates currently in the Work test stage.

Archive John Smith's application for the Senior Engineer role with reason "Not enough experience" and send the standard rejection email.

Show me the available archive reasons and rejection email templates.

Bulk archive all candidates in Application Review for the closed Designer role.
```

## Privacy

- This server proxies requests to the [Ashby API](https://developers.ashbyhq.com/) using your own API key.
- No data is stored, logged, or sent anywhere other than Ashby's API endpoints (`api.ashbyhq.com`).
- Your API key is stored locally on your machine and is never transmitted to any third party.

## Testing

### Verify API connectivity

```bash
ASHBY_API_KEY=your-key npm run test-api
```

### Test with MCP Inspector

```bash
ASHBY_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js
```

### Run directly

```bash
ASHBY_API_KEY=your-key node dist/index.js
```

The server communicates over stdio — it will start silently and wait for MCP protocol messages.

## Development

```bash
npm install
npm run build    # compile TypeScript to dist/
npm test         # run tests
npm start        # run the built server
```