ctxfile

Client setup

ctxfile is a standard stdio MCP server, so any MCP client can run it. Pick your client; the same install serves all of them.

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.

1

Install ctxfile

One global install serves every client on the machine.

npm install -g ctxfile
2

Register the server

Run from your project directory; that is what --root . points at. Defaults to local scope (just you, this project). Add --scope project to commit it to the repo for your team, or --scope user for all your projects.

claude mcp add ctxfile -- ctxfile --root .
3

Verify

The ctxfile tools appear in the list, or run /mcp inside a session.

claude mcp list

Pro reads the other side too

Registering the server gets every client the same tools. Pro's session connectors additionally read each agent's own session history (Claude Code, Cursor, Codex, OpenCode, Gemini, Aider, OpenClaw, Hermes), so work done in one client shows up in get_context in all the others.

MCP Inspector

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

npx @modelcontextprotocol/inspector ctxfile --root .

Generic stdio config

For any client not listed above (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.