Client setup

ctxfile is a standard stdio MCP server, so any MCP client can run it. Install first: npm install -g ctxfile.

Requires Node.js 20+ on macOS and Linux, and Node.js 22+ on Windows (a native dependency ships no Node 20 Windows prebuild). Node 22 and 24 are both current LTS lines.

Claude Code

claude mcp add ctxfile -- ctxfile --root .

Run from your project directory (that's what --root . points at). Verify with claude mcp list.

Cursor

Add to .cursor/mcp.json in the project, or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "ctxfile": {
      "command": "ctxfile",
      "args": ["--root", "."]
    }
  }
}

ctxfile exposes a handful of tools, far under Cursor's 40-tool cap.

Claude Desktop

Download ctxfile.mcpb from the releases page and drag it into Settings → Extensions, or add the generic stdio JSON below to claude_desktop_config.json.

MCP Inspector

Inspect the server's tools, resources, and prompts interactively:

npx @modelcontextprotocol/inspector ctxfile --root .

Generic stdio config

For any other MCP client (Claude Desktop, Cline, Windsurf, custom SDK clients), the shape is always the same, a command plus args, spoken to over stdio:

{
  "command": "ctxfile",
  "args": ["--root", "/absolute/path/to/project"]
}

Prefer an absolute --root when the client doesn't guarantee a working directory. Add --config <path> to point at a config file outside the project root.

Troubleshooting: “command not found” (nvm / version managers)

If the client reports the server failed to start, discovered no tools, or shows only an auth item, the usual cause is not ctxfile but your Node install: desktop MCP clients (Cursor, Claude Desktop) are GUI apps that don't always inherit your shell's PATH, so a node, npx, or ctxfile managed by nvm (or a non-standard Homebrew prefix) isn't found. This affects every stdio MCP server, not just ctxfile.

The reliable fix is to use absolute paths in the config. Find yours:

which node        # e.g. /Users/you/.nvm/versions/node/v24.11.0/bin/node
npm root -g       # e.g. /Users/you/.nvm/versions/node/v24.11.0/lib/node_modules

Then point the client at the absolute Node binary running ctxfile's entry file:

{
  "mcpServers": {
    "ctxfile": {
      "command": "/Users/you/.nvm/versions/node/v24.11.0/bin/node",
      "args": [
        "/Users/you/.nvm/versions/node/v24.11.0/lib/node_modules/ctxfile/dist/cli.js",
        "--root", "."
      ]
    }
  }
}

Give the absolute node path directly rather than the ctxfile command, because the ctxfile launcher's #!/usr/bin/env node line would still need node on the client's PATH. Restarting the client from a terminal that has your PATH loaded also works, but the absolute-path config survives restarts.