What is zoxide-doctor?

Read-only local zoxide diagnostics for MCP clients.

How do I install zoxide-doctor?

Install zoxide-doctor via npm from https://registry.npmjs.org, then add the server config to your MCP client (Claude Desktop, Cursor, or VS Code).

Is zoxide-doctor open source?

Yes, zoxide-doctor is open source under the MIT license. Source code is available at https://github.com/jiankn/zoxide-doctor-mcp.

What category does zoxide-doctor belong to?

zoxide-doctor is listed under Other MCP servers on MCPFind.

zoxide-doctor — MCP Server for Other

zoxide-doctor MCP server

@agoes/zoxide-doctor-mcp gives MCP clients one local, read-only tool for diagnosing zoxide installation and shell setup. It wraps the published zoxide-doctor diagnostic core; it does not install zoxide or modify shell configuration files.

This is an independent community integration. It is not affiliated with or endorsed by the official zoxide project.

What it does

Checks whether zoxide and optional fzf are on PATH.
Checks that zoxide init produces shell initialization code.
Returns a machine-readable JSON report, including the matching zoxide.org setup and troubleshooting guides.
Reads conventional shell profile paths only when the MCP caller sets scan_config: true.

Install for an MCP client

Use an MCP client configuration that starts the local stdio server with npx:

{
  "mcpServers": {
    "zoxide-doctor": {
      "command": "npx",
      "args": ["-y", "@agoes/zoxide-doctor-mcp"]
    }
  }
}

The server exposes one tool:

diagnose_zoxide({ shell?: "bash" | "zsh" | "fish" | "powershell" | "nushell" | "elvish" | "tcsh" | "xonsh" | "posix", scan_config?: boolean })

scan_config is opt-in because it reads conventional shell-profile files. The tool never writes files or changes shell state.

Development

npm install
npm run lint
npm test
npm run validate:metadata
npm run pack:check
npm run smoke

server.json is kept version-locked to package.json and sets the MCP Registry websiteUrl to the zoxide-doctor guide.

License

MIT

Set up in your AI client

AI clientOperating system

Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.

json

{
  "mcpServers": {
    "io-github-jiankn-zoxide-doctor": {
      "command": "npx",
      "args": [
        "-y",
        "@agoes/zoxide-doctor-mcp"
      ]
    }
  }
}

Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.

Claude Desktop setup reference

Compatible MCP Clients

zoxide-doctor works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.

Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.

Cursor~/.cursor/mcp.jsonRestart Cursor for changes to take effect.

VS Code.vscode/mcp.jsonReload VS Code window for changes to take effect.

Windsurf~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect.

Claude Code.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.

zoxide-doctor