Query employee profiles, job roles, time-away requests, company info, and office locations through a standardized MCP interface.
Also known as mindstone/mcp-servers, mcp-server-humaans, @mindstone/mcp-server-humaans
- Stars
- 14
- Tools
- 16
- Downloads, 30 days
- —
- Latest version
- 0.3.1
- Last commit
- Nov 16, 2026
- License
- —
What is Humaans MCP?
Humaans queries employee profiles, job roles, time-away requests, company info, and office locations through a standardized MCP interface. It exposes 16 tools, such as configure_humaans_api_key, get_humaans_me, list_humaans_people.
Summary generated from the project's README
About Humaans MCP server
Accessing employee data and managing leave requests from within your AI assistant is what Humaans enables. This MCP server connects your Model Context Protocol host to the Humaans HR platform, allowing you to query profiles, job roles, company information, and office locations through a standardized interface. It is designed for developers and managers who need to interact with HR data using tools like Claude Desktop, Cursor, or VS Code.
To use this server, you must provide a HUMAANS_API_KEY via environment variables. The server provides 16 specific tools categorized into people, job roles, time-away, company, and teams. For example, you can use tools to list employees, retrieve specific job role histories, or manage time-away requests such as approving or declining leave. The system includes safety measures by stripping sensitive fields like tax IDs and home addresses from detailed person responses and wrapping free-text fields in envelopes to ensure the model treats them strictly as data.
What you can do with it
- 1Manage employee leave requestsAn AI assistant can approve or decline pending time-away requests for team members.
- 2Retrieve employee profile detailsYou can ask the AI to find specific information about a staff member's role or history.
- 3Audit company office locationsA developer can query the list of all company offices and locations.
- 4Track team compositionsThe server can derive team names and member counts from the people directory.
Written from the project's README. Every use case is checked against a quote from it.
How to install Humaans MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Humaans MCP in Claude Code
$ claude mcp add --env 'HUMAANS_API_KEY=<YOUR_HUMAANS_API_KEY>' mcp-server-humaans -- npx -y @mindstone/mcp-server-humaansInstall Humaans MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server-humaans": {
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-humaans"
],
"env": {
"HUMAANS_API_KEY": "<YOUR_HUMAANS_API_KEY>"
}
}
}
}Install Humaans MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server-humaans": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-humaans"
],
"env": {
"HUMAANS_API_KEY": "<YOUR_HUMAANS_API_KEY>"
}
}
}
}Install Humaans MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server-humaans","type":"stdio","command":"npx","args":["-y","@mindstone/mcp-server-humaans"],"env":{"HUMAANS_API_KEY":"<YOUR_HUMAANS_API_KEY>"}}'Install Humaans MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server-humaans": {
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-humaans"
],
"env": {
"HUMAANS_API_KEY": "<YOUR_HUMAANS_API_KEY>"
}
}
}
}Install Humaans MCP in Codex
$ codex mcp add mcp-server-humaans --env 'HUMAANS_API_KEY=<YOUR_HUMAANS_API_KEY>' -- npx -y @mindstone/mcp-server-humaansInstall Humaans MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server-humaans] command = "npx" args = ["-y", "@mindstone/mcp-server-humaans"] [mcp_servers.mcp-server-humaans.env] HUMAANS_API_KEY = "<YOUR_HUMAANS_API_KEY>"
Install Humaans MCP in Gemini CLI
$ gemini mcp add -s user -e 'HUMAANS_API_KEY=<YOUR_HUMAANS_API_KEY>' mcp-server-humaans npx -- -y @mindstone/mcp-server-humaansInstall Humaans MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server-humaans": {
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-humaans"
],
"env": {
"HUMAANS_API_KEY": "<YOUR_HUMAANS_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @mindstone/mcp-server-humaans 0.3.1 in an isolated container with no network and no keys. It answered and listed 16 tools.
Humaans MCP tools 16
Read from the server with tools/listconfigure_humaans_api_keyActionHost-managed setup only. The user adds the Humaans API access token in Settings → Connectors in the app. Do not ask for or accept the token in chat. Get a token from https://app.humaans.io/settings/home?tokens=1 — click "Generate new token", name it (e.g., "MCP Server"), select scopes: public:read, private:read, private:write.
get_humaans_meRead-onlyGet the current authenticated user's profile from Humaans. Returns: name, email, job title, department, teams, location, status. Use this to get your own personId for other operations (e.g., creating time away). RELATED TOOLS: - create_humaans_time_away: Use the returned id as personId - list_humaans_time_away: Filter by your personId
list_humaans_peopleRead-onlyList employees from Humaans HR. By default returns only active employees. Use status filter for other groups. Returns compact summaries: id, name, email, job title, department, teams, location, status. Example: { "status": "active", "team": "Engineering", "limit": 50 } Pagination: Returns up to 'limit' results (default 50, max 250). Use 'skip' for next page. RELATED TOOLS: - get_humaans_person: Pass an employee's id to get their full profile - list_humaans_job_roles: Pass personId to see job role history
get_humaans_personRead-onlyGet full employee profile from Humaans by their ID. Returns detailed profile including: name, email, job role, department, teams, location, employment dates, contract type, working days, manager, bio, social links. Sensitive fields (tax ID, personal email, home address) are redacted for privacy. Example: { "personId": "VMB1yzL5uL8VvNNCJc9rykJz" } WORKFLOW - To find a person: 1. Call list_humaans_people to search (filter by email or team) 2. Use the person's id from the results here
list_humaans_job_rolesRead-onlyList job role history for employees in Humaans. Each person can have multiple job roles over time. The role with the most recent effectiveDate that is not in the future is the current active role. Use the asOf parameter to find what role someone had at a specific date. Example: { "personId": "VMB1yzL5uL8VvNNCJc9rykJz" } RELATED TOOLS: - list_humaans_people: Find personId to filter by
get_humaans_job_roleRead-onlyGet a specific job role by ID from Humaans. Returns: job title, department, manager (reportingTo), effectiveDate, endDate, note. Example: { "jobRoleId": "hmA5GnUq9ojK86LLKKWbiuKG" }
list_humaans_locationsRead-onlyList company locations/offices from Humaans. Returns: label, city, country, timezone for each office location. Note: Remote employees have locationId="remote" with remoteCity/remoteCountry fields on their person profile. Example: {}
get_humaans_companyRead-onlyGet company information from Humaans. Returns: company name, status, trial info, timesheet settings. Example: {}
list_humaans_time_awayRead-onlyList time away (PTO, sick leave, etc.) entries from Humaans. Filter by person, date range, or approval status. Returns: dates, type, days count, approval status, notes. Example: { "personId": "VMB1yzL5uL8VvNNCJc9rykJz" } Example: { "startDateAfter": "2024-01-01", "startDateBefore": "2024-12-31" } RELATED TOOLS: - list_humaans_people: Find personId to filter by - list_humaans_time_away_types: See available time away types - create_humaans_time_away: Request new time away
create_humaans_time_awayActionCreate a time away request in Humaans (PTO, sick leave, etc.). WORKFLOW - To request time off: 1. Call get_humaans_me to get your personId 2. Call list_humaans_time_away_types to find the timeAwayTypeId (e.g., "Paid time off") 3. Call this tool with the details Dates must be in YYYY-MM-DD format. Use startPeriod/endPeriod for half days. COMMON MISTAKES: - Don't guess timeAwayTypeId - always get it from list_humaans_time_away_types first - Dates must be YYYY-MM-DD, not ISO datetime with time/timezone
list_humaans_time_away_typesRead-onlyList available time away types in Humaans. Returns type names and IDs (e.g., "Paid time off", "Sick leave", "Working from home"). You need the type ID to create a time away request. RELATED TOOLS: - create_humaans_time_away: Use the returned id as timeAwayTypeId
list_humaans_time_away_allocationsRead-onlyList time away allocations in Humaans — which time off policy applies to each person, and from which date. Allocations link a person to a time away policy (the policy defines their allowance and balances). Use this to answer "which PTO policy is Jane on?" or "who is on the US policy?". Example: { "personId": "VMB1yzL5uL8VvNNCJc9rykJz" } RELATED TOOLS: - list_humaans_people: Find personId to filter by - list_humaans_time_away: See actual time off taken - list_humaans_time_away_types: See available time away types
Show all 16 toolsShow fewer tools
cancel_humaans_time_awayActionCancel a time away entry in Humaans (deletes it permanently). Use this to withdraw a time off request or remove an incorrect entry. The deletion cannot be undone — confirm the entry with list_humaans_time_away first. Example: { "timeAwayId": "YLlqHE4DLvGtFJ7L2qro6bTF" } RELATED TOOLS: - list_humaans_time_away: Find the timeAwayId to cancel - create_humaans_time_away: Create a new request instead
approve_humaans_time_awayActionApprove a pending time away request in Humaans (manager action). Sets the request status to approved. Use list_humaans_time_away with requestStatus="pending" to find requests awaiting review. Example: { "timeAwayId": "YLlqHE4DLvGtFJ7L2qro6bTF" } RELATED TOOLS: - decline_humaans_time_away: Decline the request instead - list_humaans_time_away: Find pending requests
decline_humaans_time_awayActionDecline a pending time away request in Humaans (manager action). Sets the request status to declined. Consider including a reviewNote so the employee knows why. Example: { "timeAwayId": "YLlqHE4DLvGtFJ7L2qro6bTF", "reviewNote": "Dates clash with the release freeze" } RELATED TOOLS: - approve_humaans_time_away: Approve the request instead - list_humaans_time_away: Find pending requests
list_humaans_teamsRead-onlyList team names in Humaans with member counts. Humaans has no dedicated teams endpoint, so this derives the team list by scanning the people directory. Use it to discover valid values for the 'team' filter on list_humaans_people. Example: {} RELATED TOOLS: - list_humaans_people: Filter employees by team name
Configuration
HUMAANS_API_KEYRequiredSecretHumaans API access token (from app settings)
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablemindstone/mcp-servers is public and reachablegithub.com/mindstone/mcp-servers ↗Pass
- Package names this repository as its source@mindstone/mcp-server-humaans names mindstone/mcp-servers as sourcenpmjs.com/package/@mindstone/mcp-server-humaans ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @mindstone/mcp-server-humaansnpmjs.com/package/@mindstone/mcp-server-humaans/v/0.3.1#prov ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-16github.com/mindstone/mcp-servers ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 6.3 / 10; weakest: Code-Review 0, SAST 0, Dependency-Update-Tool 0scorecard.dev/viewer/?uri=github.com/mindstone/mcp-servers ↗Partial 9/15
- Package name not close to a popular packageNo popular package one edit away from @mindstone/mcp-server-humaansPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model16 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@mindstone/mcp-server-humaans
Humaans HR platform MCP server for Model Context Protocol hosts. Query employee profiles, job roles, time-away requests, company info, and office locations through a standardised MCP interface.
Status
- Version: 0.3.1 · npm
- Auth: API key (
HUMAANS_API_KEY) - Tools: 16 (people, job-roles, time-away, company, teams)
- Surface: cloud-api
- Machine-readable:
STATUS.json
Requirements
- Node.js 20+
- npm
One-click install
After clicking the button, your host will prompt you to fill: HUMAANS_API_KEY.
{
"mcpServers": {
"Humaans": {
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-humaans"
],
"env": {
"HUMAANS_API_KEY": ""
}
}
}
}
Quick Start
Install & build
cd <path-to-repo>/connectors/humaans
npm install
npm run build
npx (once published)
npx -y @mindstone/mcp-server-humaans
Local
node dist/index.js
Configuration
Environment variables
HUMAANS_API_KEY— Humaans API access token (from app settings)MCP_HOST_BRIDGE_STATE— optional path to a host bridge state file used for credential managementMINDSTONE_REBEL_BRIDGE_STATE— backwards-compatible alias forMCP_HOST_BRIDGE_STATE
Host configuration examples
Claude Desktop / Cursor
{
"mcpServers": {
"Humaans": {
"command": "npx",
"args": ["-y", "@mindstone/mcp-server-humaans"],
"env": {
"HUMAANS_API_KEY": "your-api-key"
}
}
}
}
Local development (no npm publish needed)
{
"mcpServers": {
"Humaans": {
"command": "node",
"args": ["<path-to-repo>/connectors/humaans/dist/index.js"],
"env": {
"HUMAANS_API_KEY": "your-api-key"
}
}
}
}
Tools (16)
Configuration
configure_humaans_api_key— Configure the Humaans API access token
People
get_humaans_me— Get the current authenticated user's profilelist_humaans_people— List employeesget_humaans_person— Get full employee profile by IDlist_humaans_teams— List team names with member counts (derived from the people directory; Humaans has no dedicated teams endpoint)
Job roles
list_humaans_job_roles— List job role history for employeesget_humaans_job_role— Get a specific job role by ID
Time away
list_humaans_time_away— List time-away entries (PTO, sick leave, etc.)create_humaans_time_away— Create a time-away requestlist_humaans_time_away_types— List available time-away typeslist_humaans_time_away_allocations— List time-away allocations (which policy applies to each person)cancel_humaans_time_away— Cancel (permanently delete) a time-away entryapprove_humaans_time_away— Approve a pending time-away request (manager action)decline_humaans_time_away— Decline a pending time-away request (manager action)
Company
list_humaans_locations— List company locations/officesget_humaans_company— Get company information
Data handling
- Person list responses are field-allowlisted; person detail responses strip sensitive fields (tax ID, personal email/phone, home address, birthday, profile photo).
- Free-text fields authored in Humaans (time-away
note/reviewNote, job-rolenote/jobTitle/department, time-away type and policy names, team names, person profile free text such as names/bio/social links/job title, location labels/cities, the company name) are returned inside<untrusted-content>envelopes so the model treats them as data, not instructions. - Humaans API error bodies are enveloped (and non-JSON bodies capped) before they reach the model;
Retry-Afterreaches rate-limit messages only as a parsed integer, and a malformed 2xx body yields a static error rather than a parser message embedding a body snippet.
Licence
FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.
Humaans MCP questions
How do I add Humaans MCP to Claude Code?
Run claude mcp add --env 'HUMAANS_API_KEY=<YOUR_HUMAANS_API_KEY>' mcp-server-humaans -- npx -y @mindstone/mcp-server-humaans in your terminal. Add --scope user to make it available in every project.
How do I add Humaans MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Humaans MCP provide?
It exposes 16 tools, including configure_humaans_api_key, get_humaans_me, list_humaans_people, get_humaans_person, list_humaans_job_roles.
What authentication is required for the Humaans MCP server?
The server requires a Humaans API access token provided via the HUMAANS_API_KEY environment variable.
How does the server handle sensitive employee information?
Person detail responses strip sensitive fields such as tax IDs, personal contact information, home addresses, and birthdays.