cvjson-mcp

An MCP server for cv.json — give any AI assistant the power to find people who are open to work and read their structured CVs.

cv.json is the open, machine-readable CV format from cvjson.com / FreeCV. Every FreeCV portfolio publishes one at livelink.cv/<name>/cv.json.

Tools

| Tool | What it does | |------|--------------| | search_open_to_work | Search a live index of real people open to work by skills, role/title, location and recruiter facets — work type (remote/hybrid/onsite), employment type, spoken languages, visa sponsorship, minimum years of experience — with sorting and paging. Returns candidate cards + each person's cv.json URL. | | fetch_cv | Fetch a person's full machine-readable CV by slug or URL. | | validate_cv | Validate any document against the official cv.json schema. | | get_cvjson_schema | Return the cv.json JSON Schema. |

Only already-public data is returned; contact details never are.

Install

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cvjson": {
      "command": "npx",
      "args": ["-y", "cvjson-mcp"]
    }
  }
}

Restart Claude Desktop — the cvjson tools appear in the 🔌 menu.

Any MCP client (Cursor, Windsurf, custom)

Run it as a stdio server:

npx -y cvjson-mcp

Hosted HTTP endpoint (no install)

Clients that speak the Streamable HTTP transport can connect directly:

https://freecv.org/api/mcp

Try it

Once connected, ask your assistant things like:

"Find me React developers who are open to work." "Fetch the cv.json for ashley and summarise their experience." "Is this cv.json valid?" (paste one)

How it works

• fetch_cv, validate_cv and get_cvjson_schema run locally — validate_cv checks against the always-current canonical schema at cvjson.com.
• search_open_to_work is served by the hosted cv.json index (it needs the live database of who's open to work). Because the hosted server executes that tool, it also owns its contract: this package asks it for the tool's own definition at startup, so new search facets appear without a package upgrade. The bundled definition is the offline fallback.

Self-host or point at your own deployment:

CVJSON_MCP_ENDPOINT=https://your-host/api/mcp \
CVJSON_SCHEMA_URL=https://your-host/schema/v1.json \
npx -y cvjson-mcp

Requirements

Node.js ≥ 18.

License

MIT · built by FreeCV