Skip to main content
Glama
join-mcp

join-mcp

by michaeljauk

join-client

A typed TypeScript SDK, CLI and MCP server for the JOIN recruiting API. Unofficial, community-maintained.

"Buy Me A Coffee"

CI CodeQL join-sdk join-sdk downloads join-com-cli join-com-cli downloads join-mcp join-mcp downloads License: MIT


Why

JOIN publishes OpenAPI documents on docs.join.com, but no TypeScript client. This repo generates three packages from those documents:

  • join-sdk: a typed client on 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

Related MCP server: Job Board MCP Server

Packages

Package

What it is

join-sdk

Typed client on openapi-fetch, with 429 retry and paging

join-com-cli

join-com command, one subcommand per endpoint, JSON output

join-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.

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:

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):

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.

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. "JOIN" is their trademark. The JOIN API and its documentation belong to JOIN.

Support

Built by Michael Jauk. If this saves you time, consider buying me a coffee.

License

MIT © Michael Jauk, for the code in this repository.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides MCP tools for job search, inbound recruiter activity triage, conversation inbox access, and guarded profile updates.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables searching and retrieving job listings from multiple platforms through MCP.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI clients to manage JobZyn jobs and candidates through MCP tools for creating, updating, unpublishing jobs, retrieving candidate applications, and linking external IDs.
      5
      104 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-compatible agents to search live job postings, score resumes against specific postings, and create or update tracked applications through their pipeline.
      4
      MIT