Troubleshooting

Run the doctor first. npx ask-llm-mcp doctor checks Node version, PATH, every provider CLI's presence + version, and env vars. It works even when MCP can't start. 90%+ of setup issues are caught here with a clear failed-check line — fix from the bottom of the report up.

npx ask-llm-mcp doctor          # human-readable
npx ask-llm-mcp doctor --json   # machine-readable, exit 1 on error

Installation Issues

"Command not found: gemini" / "codex" / "ollama"

Click to see solution

Provider CLI is not installed or not on PATH

"PATH issue" — CLI works in terminal but MCP server says "not found"

Click to see solution

macOS GUI apps don't inherit your shell PATH

Windows NPX flag issues

Click to see solution

error: unknown option "-y" when using Claude Code on Windows

MCP server not responding (Claude Desktop cannot connect)

Click to see solution

Server fails to start or connection drops

"npm install fails: EUNSUPPORTEDPROTOCOL workspace:*"

Click to see solution

npm 9 or older choking on workspace:* in published packages

Connection & Auth

"Authentication failed" / "401 Unauthorized"

Click to see solution

Provider CLI isn't authenticated

Quota / rate limit errors (Gemini RESOURCE_EXHAUSTED, Codex 429)

Click to see solution

Provider quota exhausted

"Timeout after 210000ms"

Click to see solution

Provider call exceeded server timeout

Tool & API Issues

"Provider X is not available" / tool call rejects provider

Click to see solution

The orchestrator didn't detect the provider at startup

"Sub-agent silently produces 0-byte output" / brainstorm coordinator hang

Click to see solution

Provider process killed by sub-agent lifecycle

Model & Response Issues

Response gets cut off mid-stream

Click to see solution

MCP message size limits or executor timeout

Plugin Issues

Plugin slash commands not appearing in Claude Code

Click to see solution

Plugin not installed or not loaded

Pre-commit hook running on every Bash call, not just git commit

Click to see solution

The hook matches Bash but filters by command content

Debug Mode

Enable verbose logging:

{
  "mcpServers": {
    "ask-llm": {
      "command": "npx",
      "args": ["-y", "ask-llm-mcp"],
      "env": {
        "GMCPT_LOG_LEVEL": "debug"
      }
    }
  }
}

Logs go to stderr. Claude Desktop captures them in:

• macOS: ~/Library/Logs/Claude/mcp-server-*.log
• Windows: %APPDATA%\Claude\logs\
• Linux: ~/.config/claude/logs/

Getting Help

1. Run the doctor first: npx ask-llm-mcp doctor
2. Check GitHub Issues for similar reports
3. Open a new issue with: doctor output, your client (Claude Code/Desktop/Cursor/etc.), Node version, OS, and what you ran
4. Ask in GitHub Discussions for usage questions