hr-ai-mcp

AI-powered HR management MCP server for Claude Code and other MCP-compatible clients.

Upload CVs, search candidates with natural language, analyze resumes with GPT-4o, schedule interviews — all through conversational AI without touching a UI.

How It Works

hr-ai-mcp runs as a local MCP server. Claude (or any MCP client) talks to it via standard I/O. All data is stored on your own machine — no cloud, no SaaS, no subscription.

Claude Code ──► hr-ai-mcp (MCP Server) ──► SQLite + LanceDB (local files)
                                        └──► OpenAI API (analysis & embeddings)

Quick Start

Claude Code

Option A — CLI (Recommended):

Run this single command in your terminal:

claude mcp add hr-ai -s user -e OPENAI_API_KEY=sk-... -- npx -y hr-ai-mcp

This writes the server config directly to ~/.claude.json. Then open (or restart) Claude Code — done.

Option B — Manual config:

Open ~/.claude.json and add the hr-ai entry under mcpServers:

{
  "mcpServers": {
    "hr-ai": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "hr-ai-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Save the file, then open Claude Code — done.

Claude Desktop

Step 1. Open the Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Step 2. Add the hr-ai entry under mcpServers:

{
  "mcpServers": {
    "hr-ai": {
      "command": "npx",
      "args": ["-y", "hr-ai-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Step 3. Restart Claude Desktop — done.

Claude will automatically download and start the server on first use. Data is stored at ~/.hr-ai/ on your machine.

Requirements

| Requirement | Detail | |---|---| | Node.js | >= 20.0.0 | | OpenAI API Key | For CV analysis and semantic search | | Disk space | ~50 MB for the package + your CV data |

Without an API key: The server still runs but uses mock AI responses. CV analysis results will be placeholder data.

Data Storage

All data is stored locally at ~/.hr-ai/:

~/.hr-ai/
├── hr-ai.db      # SQLite — candidates, positions, interviews
└── vectors/      # LanceDB — CV embeddings for semantic search

No data is sent to any third party except OpenAI (for analysis and embedding generation).

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | OPENAI_API_KEY | Recommended | — | OpenAI API key for CV analysis and semantic search. Without it, mock responses are returned. | | DATABASE_PATH | No | ~/.hr-ai/hr-ai.db | Custom path for the SQLite database file. | | HR_AI_VECTORS_DIR | No | ~/.hr-ai/vectors/ | Custom directory for LanceDB vector storage. |

Tip: In Claude Desktop / Claude Code configs, set these in the "env" block of your MCP server entry. They are passed directly to the server process at startup.

Available Tools (15)

CV Management

| Tool | Description | |---|---| | cv-upload | Upload a CV from a local file path. Parses PDF/DOCX, extracts text and photo. | | cv-list | List all CVs with pagination and optional candidate filter. | | cv-get | Get full CV details including raw text content. | | cv-search | Semantic search across all CVs using natural language. | | cv-analyze | Analyze a CV with GPT-4o — strengths, weaknesses, skills, score. Optionally evaluate fit for a specific position. |

Candidate Management

| Tool | Description | |---|---| | candidate-update | Update a candidate's recruitment status. | | candidate-note | Add an evaluation note with a 1–5 star rating to a candidate. |

Position Management

| Tool | Description | |---|---| | position-create | Create a new job opening. | | position-list | List positions with status and department filters. | | position-get | Get full position details and interview statistics. | | position-match | AI-powered candidate matching — finds and ranks the best candidates for a position. |

Interview Management

| Tool | Description | |---|---| | interview-schedule | Schedule an interview (online, onsite, or phone). | | interview-update | Update interview details or status (completed, cancelled). | | interview-list | List interviews with filters for status, candidate, position, and date range. |

Dashboard

| Tool | Description | |---|---| | dashboard-stats | Get system-wide statistics — total candidates, open positions, scheduled interviews. |

Example Workflow

You: Upload the CV at /Users/john/Downloads/ali_yilmaz.pdf for Ali Yılmaz, email [email protected]

Claude: [calls cv-upload] ✓ CV uploaded. Candidate ID: cnd_abc123, CV ID: cv_xyz789

You: Analyze Ali's CV

Claude: [calls cv-analyze] Score: 87/100. Strong: 8 years Python, AWS certified.
        Weak: No team lead experience. Skills: Python, FastAPI, PostgreSQL, Docker

You: Create a Senior Backend Developer position in the Engineering department

Claude: [calls position-create] ✓ Position created. ID: pos_def456

You: Who are the best candidates for the Senior Backend Developer role?

Claude: [calls position-match] Top 3 matches:
        1. Ali Yılmaz — 91% match (Python expert, AWS)
        2. ...

You: Schedule an interview with Ali for next Monday at 2pm, online, with Ahmet Bey

Claude: [calls interview-schedule] ✓ Interview scheduled for 2025-02-24 at 14:00

Candidate Status Flow

new → screening → interviewing → offered → hired
                                        └──→ rejected

Use candidate-update to move candidates through the pipeline.

Local Development

git clone https://github.com/dolusoft/hr-ai-mcp.git
cd hr-ai-mcp
npm install

# Copy env
cp .env.example .env
# Add your OPENAI_API_KEY to .env

# Run in dev mode
npm run dev

# Build
npm run build

Use local build with Claude Code

{
  "mcpServers": {
    "hr-ai": {
      "command": "node",
      "args": ["/absolute/path/to/hr-ai-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Tech Stack

| Layer | Technology | |---|---| | MCP Protocol | @modelcontextprotocol/sdk | | AI (analysis & ranking) | OpenAI GPT-4o | | Embeddings | OpenAI text-embedding-3-large | | Vector Search | LanceDB (embedded, no Docker) | | Structured DB | SQLite + Drizzle ORM | | Document Parsing | pdf-parse, mammoth | | Build | tsup |

License

MIT © Dolusoft