zoxide-doctor

io.github.jianknPublished by GitHub account jianknv0.1.2Updated Oct 24, 2026

Read-only local zoxide diagnostics for MCP clients.

VerifiedSTDIODesktop onlyDeveloper Tools

Overview

AI-generated overview

Read-only local MCP server that diagnoses zoxide installation and shell setup, returning a JSON report with matching setup guides.

What you can do
  • Check whether zoxide and optional fzf are on PATH
  • Verify that zoxide init produces shell initialization code
  • Return a machine-readable JSON report with links to setup and troubleshooting guides
  • Optionally read conventional shell profile files when scan_config is enabled
When to use it
Useful when an assistant is helping someone debug why zoxide directory jumping does not work, or verifying a fresh zoxide install and shell initialization across bash, zsh, fish, PowerShell and other shells.
Requirements
Runs as a local stdio process started with npx from the npm package; requires Node.js and a local zoxide installation to inspect. No authentication, API keys or environment variables are declared. Desktop client only.
Before you install
Read-only: it does not install zoxide or modify shell configuration. Setting scan_config to true makes it read conventional shell profile files, which may contain sensitive content, so enable it only when needed. It is an independent community integration, not affiliated with the official zoxide project.

Installation

In SourceWeft

  1. Open zoxide-doctor in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

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

The server exposes one tool:

text
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

bash
npm installnpm run lintnpm testnpm run validate:metadatanpm run pack:checknpm run smoke

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

License

MIT

Source: README.md at commit e9429c4

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts