# zoxide-doctor [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/jiankn/zoxide-doctor-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 178  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/zoxide-doctor

## Description
Read-only local zoxide diagnostics for MCP clients.

## Tools
Capabilities this server exposes over MCP:

- **diagnose_zoxide** — Run read-only local diagnostics for zoxide PATH availability, shell initialization, and optional fzf support. Shell profile content is read only when scan_config is true.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## 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:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/zoxide-doctor/readme_