humaans-mcp

Read-only MCP server for the Humaans HRIS API. Exposes 33 tools for querying people, reporting chains, compensation, time away, and more.

Reporting chains are modelled in Humaans as a directReports array on each manager (no back-pointer on reports), so the walk-up tool fetches the full people list once and builds a child→parent index locally.

Install

Requires uv. From this directory:

uv sync

Configure

The server reads the API token from HUMAANS_API_TOKEN. Create a token in Humaans (Settings → API tokens, read scopes only).

Run

HUMAANS_API_TOKEN=your_token_here uv run humaans-mcp

The server speaks MCP over stdio.

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "humaans": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/totte/code/humaans-mcp",
        "run",
        "humaans-mcp"
      ],
      "env": {
        "HUMAANS_API_TOKEN": "7dOUXlJfnog7hK1FFl87LSaiAQ7720Ig"
      }
    }
  }
}

Restart Claude Desktop. The humaans server should appear in the MCP menu.

Tools

• Identity: get_me, get_token_info

• People: list_people, get_person, find_person_by_email, search_people_by_name

• Reporting chain: get_direct_reports, get_reporting_chain_up, get_reporting_chain_down, count_reports

• Org: list_companies, get_company, list_job_roles, get_job_role, list_locations, list_spaces

• Compensation: list_compensations, get_compensation, list_compensation_types, get_compensation_type

• Time away: list_time_away, get_time_away, list_time_away_types, list_time_away_allocations, list_time_away_policies, list_public_holidays, list_public_holiday_calendars

• Other: list_bank_accounts, list_emergency_contacts, list_equipment, list_documents, list_custom_fields, list_custom_values