@aicandidatehub/mcp

@aicandidatehub/mcp

An MCP server for CandidateHub — providing AI agents with tools to manage profiles, resumes, jobs, and compensation data.

One-click install for Claude Desktop

No Node, no npm, no config file — Claude Desktop ships its own runtime:

• Download the bundle (aicandidatehub-mcp-latest.mcpb, ~3.5MB, always the latest release)
• Open it with Claude Desktop (double-click, or drag onto Settings → Extensions)
• When prompted, paste a Personal Access Token from aicandidatehub.com/account/mcp-tokens

Prefer npx / another MCP client? See the setups below.

Features

• Profile Management — fetch and manage your candidate profile
• Resume Ingestion — import resumes from text, URLs, or file uploads
• Job Tracking — import and track job opportunities
• Job Analysis — analyze fit between your profile and job postings
• CV Generation — generate role-customized resumes
• Cover Letters — generate tailored cover letters
• Compensation Intelligence — lookup salary and benefits benchmarks

Quick Start

# 1. Mint a Personal Access Token (format chmcp_…) at:
#    https://www.aicandidatehub.com/account/mcp-tokens
export CANDIDATEHUB_TOKEN=chmcp_your_token_here

# 2. Run the server (no install needed):
npx -y @aicandidatehub/mcp

Then point your MCP client at it — see the client-specific setups below.

Installation

Prerequisites

• Node.js 20 or later
• A CandidateHub Personal Access Token (create at https://www.aicandidatehub.com/account/mcp-tokens)

Claude Desktop

Setup for Claude Desktop

• Create a Personal Access Token at https://www.aicandidatehub.com/account/mcp-tokens
• Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aicandidatehub": {
      "command": "npx",
      "args": ["-y", "@aicandidatehub/mcp"],
      "env": {
        "CANDIDATEHUB_TOKEN": "chmcp_your_token_here"
      }
    }
  }
}

• Restart Claude Desktop. The MCP server will connect automatically.

Claude Code

Setup for Claude Code

• Create a Personal Access Token at https://www.aicandidatehub.com/account/mcp-tokens
• Set your environment:

export CANDIDATEHUB_TOKEN=chmcp_your_token_here

• Start Claude Code with the MCP server:

npx @aicandidatehub/mcp

Cursor

Setup for Cursor

• Create a Personal Access Token at https://www.aicandidatehub.com/account/mcp-tokens
• Edit ~/.cursor/mcp_config.json:

{
  "mcpServers": {
    "aicandidatehub": {
      "command": "npx",
      "args": ["-y", "@aicandidatehub/mcp"],
      "env": {
        "CANDIDATEHUB_TOKEN": "chmcp_your_token_here"
      }
    }
  }
}

• Restart Cursor.

OpenClaw

Setup for OpenClaw

• Create a Personal Access Token at https://www.aicandidatehub.com/account/mcp-tokens
• Configure in your OpenClaw settings:

{
  "servers": {
    "aicandidatehub": {
      "command": "npx -y @aicandidatehub/mcp",
      "env": {
        "CANDIDATEHUB_TOKEN": "chmcp_your_token_here"
      }
    }
  }
}

Codex

Setup for Codex

Install and run directly:

npm install -g @aicandidatehub/mcp
export CANDIDATEHUB_TOKEN=chmcp_your_token_here
aicandidatehub-mcp

Goose

Setup for Goose

• Create a Personal Access Token at https://www.aicandidatehub.com/account/mcp-tokens
• Edit your Goose config:

mcpServers:
  aicandidatehub:
    command: npx
    args:
      - '-y'
      - '@aicandidatehub/mcp'
    env:
      CANDIDATEHUB_TOKEN: chmcp_your_token_here

• Restart Goose.

Available Tools

18 tools ship in this package:

Profile & Resume

• get_profile — Fetch your candidate profile
• import_resume_from_text — Import a resume from plain text
• list_cv_profiles — List your stored CV / profile variants

Jobs

• import_job_from_url — Import a job posting from a URL
• list_jobs — List imported job opportunities
• get_job — Get details of a specific job
• track_job — Add a job to your application tracker
• list_tracked_jobs — List jobs in your application tracker
• get_tracked_job — Get one tracked job's details and status

Analysis & Generation

• analyze_job_fit — Analyze how well your profile matches a job
• rewrite_cv_for_job — Generate a role-customized resume (one file per call; see "Storage & File Output" below)
• list_generated_cvs — List previously-generated tailored CVs
• get_cv_download_url — Mint a fresh short download URL for an existing CV
• generate_cover_letter — Generate a tailored cover letter

Compensation

• analyze_compensation_for_job — Analyze compensation for a specific job
• get_compensation_for_role — Look up salary benchmarks for a role

Account & Meta

• signup_url — Generate a signup link
• get_server_info — Report the MCP server version, commit SHA, environment, and tool count

Storage & File Output

rewrite_cv_for_job produces exactly one file per call in the requested export_format (docx default, or pdf). Multi-template / multi-format variants in a single call are intentionally not supported — each variant requires a separate call.

Files are written to the private cv-exports Supabase Storage bucket with this path layout:

cv-exports/<user_id>/<cv_id>/<template>-<YYYYMMDD-HHMMSS>.{docx|pdf}

• <user_id> — the auth user that owns the CV
• <cv_id> — the job_linked_cvs.id of the persisted row
• <template> — the save-side template (e.g. tech, executive)
• <YYYYMMDD-HHMMSS> — UTC timestamp at render time

Each call inserts exactly one row in public.cv_short_links (the table that backs the /d/<code> redirect) with the corresponding (cv_id, format) pair.

Legitimate multi-row case. A single cv_id may have more than one row in cv_short_links (and more than one object in cv-exports/<user_id>/<cv_id>/) when:

• The user calls rewrite_cv_for_job again with a different export_format (e.g. originally docx, later pdf), OR
• The user calls get_cv_download_url after the original short URL expired (re-mint preserves the original format).

In both cases, each row still represents one historical export. There is no path that produces multiple files from one call.

The MCP response always carries the most recently minted short URL via data.export.short_url, plus the underlying long signed URL via data.export.url.

Environment Variables

• CANDIDATEHUB_TOKEN — Your Personal Access Token (required by all API-backed tools). Mint one at https://www.aicandidatehub.com/account/mcp-tokens; it has the form chmcp_…. The server starts and lists its tools without it (get_server_info and signup_url work tokenless); any other tool call without a valid token returns an error pointing you to the mint URL.
• CANDIDATEHUB_API_BASE — API endpoint (defaults to https://www.aicandidatehub.com). The apex (aicandidatehub.com) is intentionally not the default: Cloudflare 301-redirects apex → www, and 301 drops POST bodies → PAT exchange fails with 405. If you must use the apex, configure Cloudflare to issue 308 (or set this variable explicitly).
• MCP_CLIENT — Client identifier for tracking (defaults to 'unknown')

Development

npm install
npm run build
npm test
npm run test:integration  # Requires MCP_INTEGRATION=1 and MCP_TEST_PAT
npm run dev              # Watch mode

License

Proprietary — CandidateHub