Recruit CRM MCP Server

Local stdio MCP server for Recruit CRM's Public API. Access your candidates, jobs, companies, tasks, meetings, notes, call logs, and more directly from AI tools like Claude and Codex.

Install

Option 1: Claude Desktop Extension (Recommended)

1. Download and install Claude Desktop, then sign in
2. Download the latest recruitcrm-mcp-server.mcpb from the Releases page
3. Double-click to install, or drag it into Claude Desktop
4. Enter your Recruit CRM API token when prompted (found in Recruit CRM → Admin Settings → API)

Option 2: npm Package (for any MCP client)

{
  "mcpServers": {
    "recruit-crm": {
      "command": "npx",
      "args": ["-y", "recruitcrm-mcp-server"],
      "env": {
        "RECRUITCRM_API_TOKEN": "<your-api-token>"
      }
    }
  }
}

Codex for Mac

In the Codex Mac app:

1. Open Settings → MCP Servers → Add server
2. Enter name recruit_crm
3. Select STDIO
4. Set Command to launch to npx
5. Add arguments -y and recruitcrm-mcp-server
6. Add environment variable RECRUITCRM_API_TOKEN with your Recruit CRM API token
7. Leave Environment variable passthrough empty
8. Leave Working directory blank unless you need a custom launch directory, then save

Manual Codex config fallback:

[mcp_servers.recruit_crm]
command = "npx"
args = ["-y", "recruitcrm-mcp-server"]

[mcp_servers.recruit_crm.env]
RECRUITCRM_API_TOKEN = "<your-api-token>"

Codex MCP stdio servers use command, args, and env fields as documented in the Codex MCP docs.

Mac users: If you get "Failed to spawn process", use the full path to npx (e.g. /usr/local/bin/npx) as the command.

Example Prompts

Once installed, try asking Claude:

• "Show me open jobs for Acme Corp"
• "What companies do we have in the fintech space?"
• "What tasks are due this week?"
• "Pull up recent notes on John Smith"
• "Show call logs from last month"
• "Show me Frank's progression across all jobs"
• "How many candidates are in Interview hiring stage for Sales Consultant?"
• "Assign Jane Doe to the Operations Analyst job"
• "Move John Smith to the Interview stage for the Senior Engineer role"

Tools

Ownership prompts: when a user says "my", "mine", or "owned by me", treat that as an owner-scoped request where the API supports owner filters. Resolve the Recruit CRM user id via list_users when needed, then use owner_id on search_candidates, search_jobs, search_companies, search_contacts, search_tasks, or search_meetings. search_notes, search_call_logs, and search_hotlists do not support owner filters; use an owner-scoped upstream search when applicable or explain the limitation.

Tool	Description
search_candidates	Search candidates and return compact summaries for large result sets. Returns slug, which can be used for candidate detail lookup or Recruit CRM app links. Set include_contact_info: true to also include email, contact_number, and linkedin on each result (opt-in; off by default). Same flag is available on list_candidates.
list_candidates	List all candidates with pagination and sorting only (no filter required). Use search_candidates when you have filter criteria.
create_candidate	Create one candidate or update a confirmed duplicate via existing_candidate_slug, then optionally add up to 10 latest work history rows and up to 10 latest education history rows. Requires at least one of first_name or last_name; create calls require owner_id and created_by, and update calls require updated_by (resolve the acting user with list_users). Always check duplicates first with search_candidates using email, contact_number, or linkedin; duplicate messages label both candidate_slug and candidate_id so the slug is not confused with the numeric ID.
search_jobs	Search jobs and return compact summaries for large result sets. Returns job, company, and contact slugs, including hiring_pipeline_id for stage lookup. Supports client-side job_status filtering.
list_jobs	List all jobs with pagination and sorting only, including hiring_pipeline_id. Use search_jobs when you have filter criteria.
search_companies	Search companies and return compact summaries for large result sets. Returns company slug and related contact slugs for Recruit CRM app links.
list_companies	List all companies with pagination and sorting only. Use search_companies when you have filter criteria.
search_contacts	Search contacts and return compact summaries for large result sets. Requires at least one real filter; sort_by, sort_order, page, exact_search, and include_contact_info do not count by themselves. Set include_contact_info: true to also include email, contact_number, and linkedin on each result (opt-in; off by default).
list_contacts	List contacts with pagination and sorting only. Use this for unfiltered recent/all-contact requests. Supports the same opt-in include_contact_info flag as search_contacts.
list_users	List Recruit CRM users with compact id, first_name, last_name, and status fields. Set include_teams: true only when team memberships are needed. Set include_contact_info: true to also include email and contact_number.
search_hotlists	Search hotlists by required related_to_type and optional name / shared filters. Broad searches return compact rows with related_count only. When name is provided, results also include full related_slugs.
create_hotlist	Create one Recruit CRM hotlist. Requires created_by as a Recruit CRM user id and shared as 0 or 1. This is a mutating non-destructive tool; use add_records_to_hotlist to add records afterward.
add_records_to_hotlist	Add up to 10 record slugs to an existing hotlist. This is an additive write tool. It runs sequentially, ignores duplicate input slugs, and returns { hotlist_id, requested_count, successful_count, failed_count, added_slugs, errors } instead of failing the whole batch.
search_tasks	Search tasks and return compact task summaries with related entity context.
list_task_types	List compact task type rows with id and label. Use this before create_task to resolve the intended task_type_id.
create_task	Create one Recruit CRM task. Requires task_type_id, title, description, reminder, start_date, owner_id, and created_by; supports basic HTML/rich text and returns compact output without the related entity payload.
search_meetings	Search meetings and return compact meeting summaries with scheduling metadata.
list_meeting_types	List compact meeting type rows with id and label. Use this before create_meeting to resolve the intended meeting_type_id.
create_meeting	Create one Recruit CRM meeting. Requires title, reminder, start_date, end_date, owner_id, and created_by. Calendar invites are suppressed by default; to send them set do_not_send_calendar_invites: false, but only do this when the user explicitly asks.
search_notes	Search notes and return compact note summaries with related entity context.
list_note_types	List compact note type rows with id and label. Use this before create_note to resolve the intended note_type_id.
create_note	Create one Recruit CRM note. Requires note_type_id, created_by, related entity slug/type, and description; supports basic HTML/rich text and returns compact output without the related entity payload.
search_call_logs	Search call logs and return compact call summaries with related entity context.
get_candidate_details	Fetch full details for up to 10 candidates in parallel by slug. Duplicates are deduplicated. Returns { requested_count, successful_count, failed_count, candidates, errors } and does not fail the whole call when one slug is bad.
get_job_details	Fetch one job by slug and return the raw Recruit CRM payload.
get_company_details	Fetch full details for up to 10 companies in parallel by slug. Returns { requested_count, successful_count, failed_count, companies, errors } and does not fail the whole call when one slug is bad.
get_contact_details	Fetch full details for up to 10 contacts in parallel by slug. Returns { requested_count, successful_count, failed_count, contacts, errors } and does not fail the whole call when one slug is bad.
get_job_assigned_candidates	Fetch assigned candidates for one job and return compact assignment summaries. The job's hiring_pipeline_id is included — use hiring_pipeline_id 0 with list_candidate_hiring_stages for the master pipeline stages.
list_candidate_hiring_stages	List compact candidate hiring stage rows for a hiring pipeline. Pass hiring_pipeline_id 0 (default) for the Master Hiring Pipeline or a job's hiring_pipeline_id for job-specific stages. Returns status_id values needed for update_candidate_hiring_stage.
assign_candidate_to_job	Assign a candidate to a job. Requires candidate_slug, job_slug, and updated_by (Recruit CRM user id). Write tool — use only when explicitly requested.
update_candidate_hiring_stage	Update a candidate's hiring stage for a specific job assignment. Requires candidate_slug, job_slug, status_id (resolve via list_candidate_hiring_stages), stage_date, and updated_by. Write tool — use only when explicitly requested.
list_job_statuses	List job pipeline statuses (Open, Closed, On Hold, plus custom labels) with id and label for resolving status names to the numeric job_status_id used by search_jobs.
get_candidate_job_assignment_hiring_stage_history	Fetch one candidate's job assignment hiring stage history.
list_candidate_custom_fields	List curated candidate custom field metadata. Set include_non_searchable: true to also include fields that cannot be used as search filters (e.g. file, user, company fields).
get_candidate_custom_field_details	Fetch curated details for one candidate custom field, including full option values.
get_custom_field_dependencies	Get parent-child dependency relationships for custom fields of a given entity type (candidates, contacts, companies, jobs, deals). Pass field_id to narrow results to the dependency subtree for one specific field. Call this before setting a child custom field — the parent field_id and its value must also be included in the custom_fields array or the API will reject the request with a dependency error.
analyze_job_pipeline	Diagnose a single job's hiring pipeline in one call: stage distribution, days-in-current-stage, idle candidates, bottleneck verdict, recent activity, and suggested next actions. Set include_time_metrics: true for time-to-hire and time-to-stage data (extra API calls; default false).

Most tools are read-only (readOnlyHint: true). create_candidate, create_hotlist, add_records_to_hotlist, create_task, create_meeting, create_note, assign_candidate_to_job, and update_candidate_hiring_stage are mutating tools and should only be used when explicitly requested by the user.

create_candidate notes: pass source only when the user provides one. URL fields such as linkedin, github, facebook, twitter, xing, avatar, and resume are normalized with https:// when the scheme is missing. For candidate custom fields, resolve the field id with list_candidate_custom_fields, confirm dropdown or multiselect values with get_candidate_custom_field_details, and call get_custom_field_dependencies for any child field to ensure the parent field and its value are also included in the custom_fields array.

Open In Recruit CRM

Recruit CRM entities follow the app URL pattern https://app.recruitcrm.io/<entity>/<slug>.

Entity	App Link Pattern
Candidate	https://app.recruitcrm.io/candidate/{slug}
Company	https://app.recruitcrm.io/company/{slug}
Contact	https://app.recruitcrm.io/contact/{slug}
Job	https://app.recruitcrm.io/job/{slug}
Deal	https://app.recruitcrm.io/deal/{slug}

Configuration

Required

• RECRUITCRM_API_TOKEN — your Recruit CRM API token

Optional

• RECRUITCRM_BASE_URL — default: https://api.recruitcrm.io/v1
• RECRUITCRM_TIMEOUT_MS — default: 10000
• RECRUITCRM_DEBUG_SCHEMA_ERRORS — default: false

Privacy And Security

• Runs locally on your machine over stdio — no data sent to third parties
• API tokens read from environment variables only; stored securely in OS keychain when using the .mcpb extension
• Search results exclude emails, phone numbers, and other sensitive fields by default
• Search and detail tools are read-only by default
• create_candidate, create_hotlist, add_records_to_hotlist, create_task, create_meeting, create_note, assign_candidate_to_job, and update_candidate_hiring_stage are write tools; this extension still does not expose delete operations
• See our full Privacy Policy

Troubleshooting

"Server disconnected" or "Failed to spawn process"

• Make sure Node.js ≥ 20 is installed (nodejs.org)
• On Mac, use the full path to npx (run which npx in terminal to find it)
• Use the .mcpb install option instead — it doesn't need Node set up

"Authentication failed" / 401 errors

• Verify your API token at Recruit CRM → Admin Settings → API
• Ensure the token has the required permissions for the tools you're using

Other issues

• File an issue at GitHub Issues
• Contact support: support@recruitcrm.io

Local Development

npm install
npm run build
npm test

License

MIT — see LICENSE