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
