deephr-mcp

deephr-mcp

Read-only MCP server exposing deepHR's modules to MCP clients (Claude Desktop / Claude Code). It proxies read calls to the deepHR backend /api/* over HTTP, authenticating with a service account and refreshing the JWT on 401.

Install (clients)

No clone needed — run it straight from GitHub with npx:

claude mcp add deephr -s user \
  -e DEEPHR_API_URL=https://deephr.your-cloud-domain.com \
  -e DEEPHR_EMAIL=you@yourco.com \
  -e DEEPHR_PASSWORD=... \
  -- npx -y github:leevydanomalik/deephr-mcp

(If/when published to npm, swap the last line for npx -y deephr-mcp.)

-s user makes it global (available in every project on that machine). Each user only changes DEEPHR_API_URL (the deployed backend) and their own login. Needs Node >= 18.

Updating to a new release

The config tracks the main branch, so a new release is just a new commit here. Two things to know when pulling an update:

1. npx caches git installs. Reconnecting the MCP server re-runs the npx

command, but npx may relaunch a cached older build instead of re-fetching main. To guarantee you get the latest, clear the cache first, then reconnect:

   rm -rf ~/.npm/_npx        # drop npx's cached git installs

(Alternatively pin a commit — npx -y github:leevydanomalik/deephr-mcp#<sha> — for a deterministic install, at the cost of editing config each release.)

1. The backend must have the routes too. This server only proxies; new tools

call new /api/* endpoints. The backend at your DEEPHR_API_URL must be running a version that has them, or the new operations return 404. Updating the MCP client alone is not enough.

Run (local dev)

DEEPHR_EMAIL=svc@yourco.com DEEPHR_PASSWORD=... bun run src/server.ts

The backend must be running (default http://localhost:4445).

Build & publish (maintainers)

bun run build     # bundles src/ -> dist/server.js (node ESM, shebang, npx-runnable)
npm publish       # prepublishOnly runs the build automatically

deephr-mcp is an unscoped public package — npm login once, then npm publish.

Env

| Var | Default | Purpose | |---|---|---| | DEEPHR_API_URL | http://localhost:4445 | Backend base URL | | DEEPHR_EMAIL | (required) | Service-identity login (use an admin/superadmin account) | | DEEPHR_PASSWORD | (required) | Service-identity password |

Register in Claude Code / Desktop

{
  "mcpServers": {
    "deephr": {
      "command": "bun",
      "args": ["run", "/ABSOLUTE/PATH/deepHR/mcp/src/server.ts"],
      "env": {
        "DEEPHR_API_URL": "http://localhost:4445",
        "DEEPHR_EMAIL": "svc@yourco.com",
        "DEEPHR_PASSWORD": "..."
      }
    }
  }
}

Tools

~16 facade tools (deephr_payroll, deephr_employees, …). Each takes { operation, params }. See a tool's description for its operation catalog.

Maintaining the registry

Routes are scanned from backend/src/app/api:

bun run scan   # regenerates src/registry/<facade>.ts + index.ts

Hand-tune hot operations (better summaries, real query schemas) in src/registry/annotations.ts — that layer survives re-scans.