humaans-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@humaans-mcp Show me the reporting chain for Jane Smith"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 syncRelated MCP server: sql-explorer-mcp
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-mcpThe 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_infoPeople:
list_people,get_person,find_person_by_email,search_people_by_nameReporting chain:
get_direct_reports,get_reporting_chain_up,get_reporting_chain_down,count_reportsOrg:
list_companies,get_company,list_job_roles,get_job_role,list_locations,list_spacesCompensation:
list_compensations,get_compensation,list_compensation_types,get_compensation_typeTime 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_calendarsOther:
list_bank_accounts,list_emergency_contacts,list_equipment,list_documents,list_custom_fields,list_custom_values
Available Tools
33 toolscount_reportsA
Count reports for a person. recursive=False gives direct reports only; True gives the full subtree size.
Inputs: person_id (required), recursive. Returns: object
find_person_by_emailA
Find one person by exact email match. Returns the person object, or null if not found.
Inputs: email (required). Returns: result
get_companyC
Retrieve a company by id.
Inputs: company_id (required). Returns: object
get_compensationA
Retrieve a single compensation record by id.
Inputs: compensation_id (required). Returns: object
get_compensation_typeB
Retrieve a single compensation type by id.
Inputs: type_id (required). Returns: object
get_direct_reportsA
List direct reports of the given person. Reads the directReports array on the person record.
Inputs: person_id (required). Returns: result
get_job_roleB
Retrieve a single job role by id.
Inputs: job_role_id (required). Returns: object
get_meA
Return the authenticated user for the current API token.
Inputs: no named parameters. Returns: object
get_personA
Retrieve a single person by their Humaans id. Employee-scoped custom field values are merged onto the person object as top-level keys named after the field (e.g. "Level": "IC5", "Cost Center": ["R&D"]). Native attributes win on name collisions.
Inputs: person_id (required). Returns: object
get_reporting_chain_downA
Build the subtree of reports under the given person, up to max_depth levels. Uses a single fetch of all people then walks directReports locally.
Inputs: person_id (required), max_depth. Returns: object
get_reporting_chain_upB
Walk the management chain upward from the given person. Returns an ordered list starting with the person and ending at the top of the chain (someone with no manager).
Inputs: person_id (required), max_depth. Returns: result
get_time_awayC
Retrieve a single time-away record by id.
Inputs: time_away_id (required). Returns: object
get_token_infoA
Return metadata about the current API token (scopes, owner, etc.).
Inputs: no named parameters. Returns: object
list_bank_accountsB
List bank accounts. Optionally filter by personId.
Inputs: person_id.
list_companiesA
List all companies in the Humaans account.
Inputs: no named parameters.
list_compensationsC
List compensation records (salary, bonus, etc.). Optional filters: personId, typeId.
Inputs: person_id, type_id, limit, skip.
list_compensation_typesA
List all compensation types configured in the account (salary, bonus, commission, equity, etc.).
Inputs: no named parameters.
list_custom_fieldsA
List all configured custom fields.
Inputs: no named parameters.
list_custom_valuesB
List custom field values. Optionally filter by personId.
Inputs: person_id.
list_documentsB
List documents. Optionally filter by personId.
Inputs: person_id.
list_emergency_contactsB
List emergency contacts. Optionally filter by personId.
Inputs: person_id.
list_equipmentA
List equipment assigned to people. Optionally filter by personId.
Inputs: person_id.
list_job_rolesC
List job roles (historical and current job assignments). Optionally filter by personId.
Inputs: person_id, limit, skip.
list_locationsA
List all configured work locations (typically countries/regions for remote teams).
Inputs: no named parameters.
list_peopleA
List people (employees). Optional filters: email, locationId, status. Paginated via limit/skip (max 250). Note: Humaans has no manager-side filter on this endpoint — use get_direct_reports for that.
Inputs: email, location_id, status, limit, +1 more.
list_public_holiday_calendarsA
List all configured public holiday calendars.
Inputs: no named parameters.
list_public_holidaysC
List public holidays. Optional filters: calendarId, year.
Inputs: calendar_id, year.
list_spacesB
List all physical office spaces.
Inputs: no named parameters.
list_time_awayC
List time-away records. Optional filters: personId, startDate, endDate (YYYY-MM-DD).
Inputs: person_id, start_date, end_date, limit, +1 more.
list_time_away_allocationsC
List time-away allocations. Optionally filter by personId.
Inputs: person_id.
list_time_away_policiesB
List all time-away policies.
Inputs: no named parameters.
list_time_away_typesA
List all time-away types (vacation, sick, parental, etc.).
Inputs: no named parameters.
search_people_by_nameA
Case-insensitive substring search over firstName/lastName/preferredName across all people. Pulls the full people list then filters client-side.
Inputs: query (required), limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Tools are clearly separated by entity (people, compensation, time away, etc.) and operation (list, get, find, search, count). There is minimal overlap; get_direct_reports is distinct from list_people, and count_reports serves a different purpose from reporting chains.
All tool names follow a consistent verb_noun pattern using snake_case, with verbs like list, get, find, search, count applied uniformly. No mixing of styles or vague verbs.
33 tools is slightly high for typical MCP servers, but each tool covers a distinct entity or operation within the HR domain. A few could potentially be merged (e.g., count_reports and get_reporting_chain_down), but overall the count is justifiable.
The tool set is entirely read-only; there are no create, update, or delete tools for any HR entity. This is a major gap for a practical HR system, as agents cannot manage data. Additional entities like departments or teams are also missing.
Maintenance
Related MCP Connectors
MCP server for SmartHR — employees, departments, dependents and employee invitations.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
MCP server for Talenta — read employee, attendance, leave, payroll and recruitment data.
The official Planning Center MCP server for interacting with your ministry's data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn open-source MCP server that imports HR CSV data into an in-memory SQLite database for structured querying and metadata retrieval. It enables users to perform read-only SQL queries and structured searches on employee data through natural language.MIT
- AlicenseNot gradedqualityFmaintenanceRead-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.MIT
- FlicenseAqualityDmaintenanceRead-only MCP server for the Tipsoi HRM API, exposing 15 tools to read employee data, attendance, leave, overtime, and more.153-
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server that proxies deepHR's API to MCP clients, enabling interaction with deepHR modules such as payroll and employees through natural language.-