@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
predict_measurement	POST /v1/predict
list_measurements	GET /v1/public/measurements
list_countries	GET /v1/countries

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)
• 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