# @slantis/mcp-teamtailor

Full-coverage, read-only MCP server for the [Teamtailor](https://www.teamtailor.com/) recruitment API.

Exposes 18 tools covering the entire Teamtailor data model — candidates, jobs, applications, offers, stages, departments, locations, users, and activities — with strict input validation and safe error handling.

> **Read-only by design.** This server makes no write calls. No candidates, jobs, or applications can be created, modified, or deleted through this MCP.

---

## Installation

```bash
npm install -g @slantis/mcp-teamtailor
# or run directly with npx (no install needed):
npx @slantis/mcp-teamtailor
```

## Configuration

Add to your Claude Code (or Claude Desktop) MCP config:

```json
{
  "mcpServers": {
    "teamtailor": {
      "command": "npx",
      "args": ["-y", "@slantis/mcp-teamtailor"],
      "env": {
        "TEAMTAILOR_API_KEY": "your-admin-api-key",
        "TEAMTAILOR_URL": "https://api.na.teamtailor.com/v1"
      }
    }
  }
}
```

### Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `TEAMTAILOR_API_KEY` | **Yes** | — | Admin API key from Teamtailor → Settings → API Keys |
| `TEAMTAILOR_URL` | No | `https://api.teamtailor.com/v1` | Base URL. Use `https://api.na.teamtailor.com/v1` for North America |
| `TEAMTAILOR_API_VERSION` | No | `20210218` | Teamtailor API version date string |

---

## Tools Reference

### Candidates
| Tool | Description |
|---|---|
| `list_candidates` | List candidates with optional date filters and pagination |
| `get_candidate` | Get full candidate details by ID |

### Jobs
| Tool | Description |
|---|---|
| `list_jobs` | List jobs — filter by status, department, or location |
| `get_job` | Get full job details by ID |

### Applications
| Tool | Description |
|---|---|
| `list_job_applications` | List applications — filter by job, candidate, or stage |
| `get_job_application` | Get application details including current stage |

### Offers
| Tool | Description |
|---|---|
| `list_job_offers` | List job offers — filter by application |
| `get_job_offer` | Get offer details including sent/accepted/rejected dates |

### Pipeline
| Tool | Description |
|---|---|
| `list_stages` | List pipeline stages — filter by job |
| `get_stage` | Get stage details by ID |

### Structure
| Tool | Description |
|---|---|
| `list_departments` | List all departments |
| `get_department` | Get department details by ID |
| `list_locations` | List all office locations |
| `get_location` | Get location details by ID |

### Users
| Tool | Description |
|---|---|
| `list_users` | List all Teamtailor users (recruiters, hiring managers) |
| `get_user` | Get user details by ID |

### Audit
| Tool | Description |
|---|---|
| `list_activities` | List activity log — filter by subject type and ID |
| `get_activity` | Get a specific activity entry by ID |

---

## Example prompts

- *"List the first 5 open jobs in Teamtailor"*
- *"Find candidates who applied in the last 7 days"*
- *"What stages does job 12345 have?"*
- *"Show me all applications for job 42 that are still in the first stage"*
- *"What's the activity history for candidate 99?"*

---

## Development

```bash
npm install
npm run dev          # run with tsx (no build needed)
npm run typecheck    # type-check without emitting
npm test             # run vitest
npm run build        # compile to dist/
```

---

## License

MIT © [Slantis](https://slantis.com)