Zoxide Doctor

What zoxide-doctor MCP server does

The zoxide-doctor MCP server exposes local diagnostics for zoxide through MCP. It checks whether the zoxide command is available on PATH, reports whether the optional fzf command is available, and verifies that zoxide init returns initialization code for the selected shell.

The result is a machine-readable JSON report. It also includes the relevant zoxide.org setup and troubleshooting guides, giving an agent links and diagnostic context it can present to a developer.

This is a community-maintained integration and is not affiliated with or endorsed by the official zoxide project. It does not install zoxide, edit shell configuration, write files, or change the current shell state.

How it works

The zoxide-doctor MCP server runs locally as a stdio process. An MCP client starts the published npm package with npx, then invokes the single exposed tool, diagnose_zoxide.

The tool accepts an optional shell value and an optional scan_config flag. Supported shells are bash, zsh, fish, powershell, nushell, elvish, tcsh, xonsh, and posix. If no shell is supplied, the client can rely on the tool's default behavior rather than selecting one explicitly.

Configuration-file inspection is opt-in. When scan_config: true is provided, the diagnostic process reads conventional shell-profile paths. This read operation is separate from the command and initialization checks, and the server does not modify the files it reads.

Setup and configuration

Add the server to an MCP client configuration using a local stdio entry:

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

After registration, call diagnose_zoxide with an optional shell and, only when needed, scan_config: true. The package also provides repository development commands for linting, tests, metadata validation, package checks, and a smoke test, but those commands are intended for contributors rather than normal MCP client setup.

Tools and capabilities

The server provides one tool:

• diagnose_zoxide({ shell?, scan_config? }): produces read-only diagnostics for zoxide and optional fzf availability, checks shell initialization output, and can inspect conventional shell-profile paths.

The zoxide-doctor MCP server is suited to agents that need structured diagnostic output instead of manually parsing terminal text. It can help distinguish a missing executable from a shell-initialization problem, while leaving remediation to the user or another tool.

Limitations and notes

Only diagnostics are provided. The server does not install zoxide or fzf, repair PATH, generate shell configuration, or apply any recommended changes. Profile scanning is limited to conventional shell-profile paths and occurs only when explicitly requested.

The integration depends on the local environment in which the stdio process runs. Its report reflects that environment's available commands and shell setup. The package is licensed under MIT.