@humanform/mcp

Humanform MCP server

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

Setup

• Build from the repo root:

pnpm --filter @humanform/mcp build

• Set your API key (from the Humanform dashboard):

export HUMANFORM_API_KEY="hf_live_..."
# optional override (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_..."
      }
    }
  }
}

For local development from this repo, use node with the path to apps/mcp/dist/index.js instead.

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

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

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 smoke script

HUMANFORM_API_KEY="hf_live_..." pnpm --filter @humanform/mcp test:smoke