@humanform/mcp

Humanform MCP server

Stdio MCP server that exposes Humanform API tools to Claude Desktop, Cursor, and other MCP clients.

Setup

• Install (optional if you use npx in your MCP config):

npm install @humanform/mcp

• Set your API key from the Humanform dashboard:

export HUMANFORM_API_KEY="hf_live_..."

Optional: override the API base URL (defaults to https://api.humanform.app):

export HUMANFORM_API_URL="https://api.humanform.app"

• Add to your MCP client config (Cursor example):

{
  "mcpServers": {
    "humanform": {
      "command": "npx",
      "args": ["-y", "@humanform/mcp"],
      "env": {
        "HUMANFORM_API_KEY": "hf_live_..."
      }
    }
  }
}

If you installed globally or locally, you can use "command": "humanform-mcp" instead of npx.

Tools

Tool	API	Description
predict_measurement	POST /v1/predict	Forward lookup: percentile → measurement value
percentile_lookup	POST /v1/percentile-lookup	Reverse lookup: measured value → percentile
list_measurements	GET /v1/public/measurements	All supported measurement names and body groups
list_countries	GET /v1/countries	Supported country codes and labels

API errors (401, 402, 404, 422, 429, etc.) are returned as MCP tool errors with the original error and message fields from the API.

Manual testing with MCP Inspector

HUMANFORM_API_KEY="hf_live_..." npx @modelcontextprotocol/inspector npx -y @humanform/mcp

Suggested checks:

• list_measurements and list_countries (no credit cost)
• predict_measurement with valid inputs (e.g. Stature, Male, 30, 50, US, cm)
• percentile_lookup with a measured value (e.g. PoplitealHeight, Female, 34, US, cm, 43.1)
• Invalid API key (expect 401)
• Unknown measurement name (expect MCP input validation or API validation_error)
• Free tier exhausted (expect 402 free_tier_exhausted if applicable)

Local development

For contributors working in the humanform-api monorepo:

pnpm --filter @humanform/mcp build
pnpm --filter @humanform/mcp test:smoke

Smoke test and MCP Inspector against a local build:

pnpm --filter @humanform/mcp build
HUMANFORM_API_KEY="hf_live_..." pnpm --filter @humanform/mcp test:smoke
HUMANFORM_API_KEY="hf_live_..." npx @modelcontextprotocol/inspector node apps/mcp/dist/index.js