Skip to content
Back to search

hr-candidate-mcp

MCP server that lets HR teams ask Claude questions about candidates from pluggable sources (official LinkedIn API, mock, ATS...)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/adnan-kutay-yuksel--hr-candidate-mcp/badge.svg)](/listings/adnan-kutay-yuksel--hr-candidate-mcp)

HTML

<a href="/listings/adnan-kutay-yuksel--hr-candidate-mcp"><img src="/api/listings/adnan-kutay-yuksel--hr-candidate-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install
npm run build

Add it to your Claude Desktop config (`claude_desktop_config.json`):

{
  "mcpServers": {
    "hr-candidates": {
      "command": "node",
      "args": ["/absolute/path/to/hr-candidate-mcp/dist/index.js"],
      "env": { "CANDIDATE_PROVIDER": "mock" }
    }
  }
}

Variables required for the `linkedin` provider are listed in `.env.example`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 80 lines
  1. # hr-candidate-mcp
  2. An open-source [Model Context Protocol](https://modelcontextprotocol.io) server that lets HR teams ask Claude (or any MCP client) questions about candidates.
  3. > "List candidates in Berlin with 5+ years of Go experience."
  4. > "Compare mock-1 and mock-3."
  5. > "Rank candidates for a role that requires Go and AWS, with Kubernetes as a nice-to-have."
  6. ## Data sources (providers)
  7. | Provider | When to use |
  8. |------------|-----------------------------------------------------------------------------|
  9. | `mock` | Development and demos. Uses fictional candidates, no credentials needed. |
  10. | `linkedin` | Organizations with **official LinkedIn API access** (Talent Solutions / Recruiter System Connect partners). Fetches data automatically. |
  11. LinkedIn APIs that expose candidate data are not publicly available. This project does **not** include scraping, browser automation, or session impersonation, and will not accept contributions that add them. The `linkedin` adapter reads the endpoints from your partner agreement via environment variables. If your response schema differs, adapt `mapCandidate` in `src/providers/linkedin.ts`.
  12. To add a new source (an ATS, etc.), implement the `CandidateProvider` interface and register it in `src/config.ts`.
  13. ## Tools
  14. - `search_candidates`: search by keywords, skills, title, and location
  15. - `get_candidate`: full profile
  16. - `compare_candidates`: side-by-side comparison of 2-10 candidates
  17. - `match_candidates_to_role`: explainable scoring against role requirements (required skills 60%, experience 30%, nice-to-have skills 10%)
  18. ## Setup
  19. ```bash
  20. npm install
  21. npm run build
  22. ```
  23. Add it to your Claude Desktop config (`claude_desktop_config.json`):
  24. ```json
  25. {
  26. "mcpServers": {
  27. "hr-candidates": {
  28. "command": "node",
  29. "args": ["/absolute/path/to/hr-candidate-mcp/dist/index.js"],
  30. "env": { "CANDIDATE_PROVIDER": "mock" }
  31. }
  32. }
  33. }
  34. ```
  35. Variables required for the `linkedin` provider are listed in `.env.example`.
  36. ## Architecture
  37. ```
  38. src/
  39. index.ts stdio MCP server
  40. tools.ts MCP tool definitions
  41. service.ts cache + comparison/scoring logic
  42. domain.ts source-agnostic candidate model
  43. config.ts environment variables -> provider selection
  44. providers/
  45. provider.ts CandidateProvider interface
  46. mock.ts fictional test data
  47. linkedin.ts official LinkedIn API adapter (OAuth 2.0 client credentials)
  48. ```
  49. ## Responsible use
  50. - Candidate data is personal data. Compliance with GDPR and other applicable privacy laws is the responsibility of the organization running the server.
  51. - Scores are a pre-screen, not a hiring decision.
  52. - Do not evaluate candidates based on protected characteristics such as age, gender, or ethnicity.
  53. ## Roadmap
  54. - [ ] Persistent cache (SQLite)
  55. - [ ] Remote (HTTP) transport with OAuth for team use
  56. - [ ] ATS providers (Greenhouse, Lever)
  57. - [ ] Unit tests and CI
  58. ## License
  59. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.