# humaans-mcp

Read-only MCP server for the [Humaans](https://humaans.io) 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](https://docs.astral.sh/uv/). From this directory:

```bash
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

```bash
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`:

```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`