join-mcp
by michaeljauk
README.md
# join-client
A typed TypeScript SDK, CLI and MCP server for the [JOIN](https://join.com) recruiting API.
Unofficial, community-maintained.
[](https://buymeacoffee.com/michaeljauk)
[](https://github.com/michaeljauk/join-client/actions/workflows/ci.yml)
[](https://github.com/michaeljauk/join-client/actions/workflows/codeql.yml)
[](https://www.npmjs.com/package/join-sdk)
[](https://www.npmjs.com/package/join-sdk)
[](https://www.npmjs.com/package/join-com-cli)
[](https://www.npmjs.com/package/join-com-cli)
[](https://www.npmjs.com/package/join-mcp)
[](https://www.npmjs.com/package/join-mcp)
[](LICENSE)
---
## Why
JOIN publishes OpenAPI documents on [docs.join.com](https://docs.join.com), but no TypeScript client.
This repo generates three packages from those documents:
- **`join-sdk`**: a typed client on [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/). It
retries on HTTP 429 and has a helper for cursor paging (`collectPages`).
- **`join-com-cli`**: the `join-com` command, with one subcommand per endpoint. It prints JSON, so
you can pipe the output through `jq`. `join-com skill install` adds a Claude Code skill to
`~/.claude/skills/join/`.
- **`join-mcp`**: a Model Context Protocol server for AI agents. It has two tools (`search`,
`execute`) instead of one tool per endpoint.
Typical use cases:
- Export the applications and CV documents of a job for a review outside JOIN
- Move applications between pipeline stages from a script
- Show your open jobs on your own careers page
- Let an AI agent summarise new applications, candidate notes and scorecards
## Packages
| Package | What it is |
| ------------------------------ | ------------------------------------------------------------ |
| [`join-sdk`](packages/sdk) | Typed client on `openapi-fetch`, with 429 retry and paging |
| [`join-com-cli`](packages/cli) | `join-com` command, one subcommand per endpoint, JSON output |
| [`join-mcp`](packages/mcp) | MCP server with two tools (`search`, `execute`) |
---
## Quick start
Create a company API token in JOIN under Company Settings → Developer → API tokens. A token belongs
to one JOIN company.
```bash
npm install -g join-com-cli
join-com auth login --profile acme # paste the token, or pipe it in
join-com jobs list
join-com applications list --job-id 123 --all | jq 'length'
join-com download "<documents[].url from an application>" -o cv.pdf
join-com skill install # optional: Claude Code skill
```
SDK:
```ts
import { collectPages, createJoinClient } from "join-sdk";
const join = createJoinClient({ token: process.env.JOIN_TOKEN! });
const { data: page } = await join.GET("/jobs", {
params: { query: { status: ["ONLINE"] } },
});
const applications = await collectPages((cursor) =>
join.GET("/applications", {
params: { query: { jobId: 123, cursor, limit: 50 } },
}),
);
```
MCP (Claude Code):
```bash
claude mcp add join -e JOIN_PROFILE=acme -- npx -y join-mcp
```
## Coverage
All 25 operations of JOIN API v3 (revision `2026-11-01`): jobs, applications and stage moves,
candidates, candidate notes, scorecards, locations, contract types, employment types, pipeline
templates and remote regions. Application documents download from pre-signed URLs.
JOIN API v2 is not supported from 1.0 on. The JOIN API has no endpoint to reject an application,
update a candidate profile or send a message. Use the JOIN web app for those. A stage move
(`move-stage`) can trigger the stage's automated emails, as a move in JOIN does.
## Development
See [AGENTS.md](AGENTS.md).
```bash
pnpm install
pnpm generate && pnpm typecheck && pnpm lint && pnpm build && pnpm test
pnpm spec:fetch # rebuild openapi.json from docs.join.com
```
## Disclaimer
Unofficial and not affiliated with [JOIN](https://join.com). "JOIN" is their trademark. The JOIN
API and its documentation belong to JOIN.
## Support
Built by [Michael Jauk](https://github.com/michaeljauk). If this saves you time, consider
[buying me a coffee](https://buymeacoffee.com/michaeljauk).
## License
[MIT](./LICENSE) © Michael Jauk, for the code in this repository.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues