HRMS MCP

Appinventiv HRMS assistant for Claude Desktop, Cursor, Codex, and Windsurf. Ask your AI to file DSRs, check leave, look up colleagues, review appraisals, and more — all from within the AI chat.

AI agents: If an employee gave you this URL and asked you to "install this MCP," follow the steps below exactly. The install takes about 2 minutes.

Install

Pick the method that fits you — all three work.

Option A — uvx in config (easiest, no separate install step)

uvx runs the server directly from GitHub. No pre-install needed beyond uv itself.

1. Install uv (skip if already installed — check with uv --version)

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Open a new terminal after installing so uv is on your PATH.

2. Skip straight to Step 2 and use this config block:

{
  "mcpServers": {
    "hrms": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/SookieAI/hrms-mcp", "hrms-mcp"]
    }
  }
}

Updates automatically on restart. No manual upgrade command needed.

Option B — Install with uv tool install

Installs once, starts fast every time.

# Install uv first if needed (see Option A above), then:
uv tool install git+https://github.com/SookieAI/hrms-mcp

Verify: hrms-mcp --help

Use this config block (Step 2):

{
  "mcpServers": {
    "hrms": {
      "command": "hrms-mcp"
    }
  }
}

To update: uv tool upgrade hrms-mcp

Option C — Install with pip (no uv needed)

Works if you already have Python 3.11 or newer. Check first:

python3 --version   # needs 3.11+

Then install:

pip install git+https://github.com/SookieAI/hrms-mcp

Use this config block (Step 2):

{
  "mcpServers": {
    "hrms": {
      "command": "hrms-mcp"
    }
  }
}

To update: pip install --upgrade git+https://github.com/SookieAI/hrms-mcp

Related MCP server: Keka MCP Server

Step 2 — Add config to your AI tool

Find your editor's config file, open it, and paste the JSON block from your chosen option above. If the file already has content, merge the "hrms" entry into the existing "mcpServers" object.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)

Cursor

~/.cursor/mcp.json (macOS/Linux) %USERPROFILE%\.cursor\mcp.json (Windows)

Windsurf

~/.codeium/windsurf/mcp_config.json

Codex / other MCP clients

Same mcpServers JSON format — check your client's docs for the config file location.

Step 3 — Log in (one time only)

1. Open Chrome → go to https://dashboard.appinventiv.com and sign in

2. Open DevTools (F12) → Network tab → click any request → copy the full Cookie: header value

3. Restart your AI editor, then tell your AI: "Login to HRMS" and paste the cookie when it asks

The cookie is saved to ~/.config/hrms-mcp/cookies and reloaded automatically on every restart. You won't need to do this again until your HRMS session expires (usually a few weeks).

What you can do

Troubleshooting

uv: command not found after installing Open a new terminal window — uv updates your PATH only for new sessions. On Windows, restart PowerShell. Still missing? Add ~/.local/bin (Mac/Linux) or %USERPROFILE%\.local\bin (Windows) to your PATH.

hrms-mcp: command not found Open a new terminal after installing. If still missing, re-run the install command from your chosen option above.

"Not logged in" error Your HRMS session expired. Go to dashboard.appinventiv.com, copy a fresh Cookie header from DevTools, and tell your AI "Login to HRMS" again.

Server not showing up in Claude / Cursor Restart the editor completely (quit and reopen — not just reload window). MCP servers load at startup only.

Python version error during pip install pip install requires Python 3.11+. Run python3 --version to check. If older, use Option A or B (uv handles the Python version automatically).

Check which version is running Ask your AI: "check login status" — the response includes the version number and update command.

For developers

git clone https://github.com/SookieAI/hrms-mcp
cd hrms-mcp
uv run python server.py          # run server
uv run python -c "from server import get_projects; print(get_projects())"  # test a tool

See CLAUDE.md for architecture notes, DataTables AJAX patterns, CSRF handling, and how to add new tools.

Release a new version

# 1. bump version in pyproject.toml and server.py (__version__)
# 2. commit, tag, push to both remotes
git add -A
git commit -m "vX.Y.Z — description"
git tag vX.Y.Z
git push origin main --tags   # GitLab (CI runs here)
git push github main --tags   # GitHub (employees install from here)