Getting Started

Three steps: install Node, install at least one provider, register the MCP server with your client. You can start with one provider (Gemini, Codex, or Ollama) and add the others anytime.

Step 1: Install Prerequisites

1. Node.js v20.0.0 or higher (LTS 20 or 22).
2. At least one provider — pick whichever fits your use case:

Which provider should I install first?

• Gemini — best for huge-context analysis (1M+ tokens). Great for whole-codebase reviews. Free tier via OAuth.
• Codex — strong at code reasoning (GPT-5.5). Good for targeted fixes and architecture critique.
• Ollama — local, private, zero-cost. Good when data can't leave your machine.

# Gemini
npm install -g @google/gemini-cli && gemini login

# Codex (requires OpenAI account)
npm install -g @openai/codex
# follow the codex CLI's auth instructions

# Ollama
# install from https://ollama.com, then:
ollama pull qwen2.5-coder:7b

You can install one or all three. The MCP server auto-detects which providers are available and only registers tools for the ones it finds.

Step 2: Configure Your MCP Client

The recommended package is ask-llm-mcp — the unified orchestrator that auto-detects all installed providers and exposes them through a single ask-llm MCP tool plus multi-llm, get-usage-stats, diagnose, and ping.

If you only want one provider, you can also install the per-provider packages directly: ask-gemini-mcp, ask-codex-mcp, ask-ollama-mcp. They expose provider-specific tools (ask-gemini with @ file syntax + sandbox + edit mode, ask-codex, ask-ollama).

Option A: Claude Code (Recommended)

# Unified — picks up all installed providers
claude mcp add --scope user ask-llm -- npx -y ask-llm-mcp

# Or per-provider (longer tool names, more granular control)
claude mcp add --scope user gemini -- npx -y ask-gemini-mcp
claude mcp add --scope user codex  -- npx -y ask-codex-mcp
claude mcp add --scope user ollama -- npx -y ask-ollama-mcp

Option B: Claude Desktop

Add to claude_desktop_config.json:

Where is my config file located?

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

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

WARNING

You must restart Claude Desktop completely for changes to take effect.

Option C: Cursor / Warp / Copilot / generic STDIO

Ask LLM works with 40+ MCP-compatible clients. Standard STDIO config:

{
  "command": "npx",
  "args": ["-y", "ask-llm-mcp"]
}

For Cursor specifically, this goes in .cursor/mcp.json. For Warp/Copilot, see your client's MCP integration docs.

---

Step 3: Verify Your Setup

Two ways to verify, depending on whether the MCP server is running:

From inside any MCP client — ask the assistant to call ping:

Use ask-llm ping to test the connection

From the terminal directly — run the doctor:

npx ask-llm-mcp doctor

The doctor checks Node version, PATH resolution, every provider CLI's presence and version, and key env vars. Use it when MCP itself can't start (server not registered, broken auth, wrong Node version) — it works outside the MCP transport.

If everything looks good, head to How to Ask for usage patterns.

---

Optional: Interactive REPL

The orchestrator binary also exposes a multi-provider REPL — switch providers, persist sessions, see token usage live:

npx ask-llm-mcp repl

Slash commands include /provider <name>, /new (fresh session), /sessions, /usage, /help, /quit. Useful for quick sanity checks and side-by-side provider comparison without setting up an MCP client.

---

Advanced Configuration (Environment Variables)

You can configure the server with env vars in your MCP client's configuration block.

Variable	Default	Description
GMCPT_LOG_LEVEL	warn	Minimum log level: debug, info, warn, error. Bump to debug if troubleshooting.
GMCPT_TIMEOUT_MS	210000	Per-provider wall-clock timeout (3.5 min). Lowered from 5 min in ADR-045 so server-side timeouts return before Claude Desktop's 4-min client cap fires. Set higher for long analyses on locally-run REPL/doctor invocations.
OLLAMA_HOST	http://localhost:11434	Ollama server URL. Override if running Ollama elsewhere.
ASK_LLM_PATH	(auto)	Override the resolved PATH used to find provider CLIs. Auto-resolved from your login shell on macOS GUI clients (ADR-047) — only set explicitly if your shell setup is unusual.