Skip to main content
Glama
humaans-mcp

humaans-mcp

by ptorsten

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

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

Available Tools

33 tools
count_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

    B3.3/5.0

    Scored across 33 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness2/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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
    • A
      license
      Not graded
      quality
      F
      maintenance
      Read-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for the Tipsoi HRM API, exposing 15 tools to read employee data, attendance, leave, overtime, and more.
      15
      3
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server that proxies deepHR's API to MCP clients, enabling interaction with deepHR modules such as payroll and employees through natural language.
      -