Installation

TeaRAGs can be installed two ways: via the setup plugin (recommended for Claude Code users) or manually for CI, non-Claude MCP clients (Cursor, Roo Code, Continue, …), or air-gapped setups.

Option A — via the Setup Plugin (Claude Code, recommended)

The tea-rags-setup plugin runs an interactive wizard that installs Node.js, the tea-rags binary, your chosen embedding provider, Qdrant, and writes the MCP entry into Claude Code.

Step 1 — Add the TeaRAGs marketplace to Claude Code:

/plugin marketplace add artk0de/TeaRAGs-MCP

Step 2 — Install the setup plugin:

/plugin install tea-rags-setup@tea-rags

Step 3 — Run the installation wizard:

/tea-rags-setup:install

The wizard walks 9 steps: environment detection, Node.js, tea-rags binary, embedding provider choice (Ollama / ONNX / OpenAI / Cohere / Voyage), Qdrant (embedded by default), performance tuning, git analytics, MCP registration, verification.

Progress is saved to ~/.tea-rags/setup-progress.json — if any step fails, re-run /tea-rags-setup:install to resume from the last successful step.

Step 4 — Install the skills plugin (final step, Claude Code only):

/plugin install tea-rags@tea-rags

This plugin is Claude Code-specific and ships the skills (/tea-rags:explore, /tea-rags:bug-hunt, /tea-rags:index, …). Other MCP clients can talk to the tea-rags server directly without this plugin.

Restart Claude Code so it loads the new skills.

No containers, no build step

Qdrant is embedded — a native binary downloads automatically. No Docker or Podman required. tea-rags is installed as a global CLI — no repo to clone.

Option B — Manual Install

Use this for CI, non-Claude MCP clients, air-gapped environments, or full control over the setup.

B.1. Install Node.js 24+

macOS

# Homebrew (recommended)
brew install node@24

# Or a version manager
brew install fnm && fnm install 24 && fnm default 24

Alternatives: brew install mise / asdf / nodenv, or curl https://get.volta.sh | bash.

Linux / WSL (Debian/Ubuntu)

# NodeSource (system-wide)
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or fnm (user-level)
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 24 && fnm default 24

Alternatives: curl https://mise.run | sh, curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash.

Windows (PowerShell)

# winget (recommended)
winget install OpenJS.NodeJS.LTS

# Or fnm (version manager)
winget install Schniz.fnm
fnm install 24
fnm default 24

Alternatives: winget install Volta.Volta, winget install CoreyButler.NVMforWindows, or download from nodejs.org.

Verify: node --version prints v24.x.x.

B.2. Install `tea-rags`

npm install -g tea-rags
# or: pnpm add -g tea-rags | yarn global add tea-rags | bun add -g tea-rags

Verify: tea-rags --version.

EACCES on macOS/Linux?

Either use sudo npm install -g tea-rags, or set a user-writable prefix:

npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

B.3. Pick an Embedding Provider

Provider	When to use	Install
Ollama (recommended)	macOS (Apple Silicon), Linux/WSL + NVIDIA/AMD, any CPU host	see below
ONNX (built-in, beta)	Windows (DirectML GPU), small projects (≤100k LOC), no external process	nothing to install — pass `-e EMBEDDING_PROVIDER=onnx`
OpenAI	Cloud preferred, no local GPU	no local install — set `OPENAI_API_KEY`
Cohere / Voyage AI	Cloud, code-tuned models	no local install — set `COHERE_API_KEY` / `VOYAGE_API_KEY`

Platform-specific recommendations (from the setup plugin):

Platform	GPU	LOC	Recommended
macOS (Apple Silicon)	apple	any	Ollama (Metal)
macOS (Intel)	intel	≤100k	ONNX (CPU)
macOS (Intel)	intel	>100k	Ollama (CPU)
Linux / WSL	nvidia	any	Ollama (CUDA)
Linux	amd	any	Ollama (ROCm)
Linux / WSL	none / intel	≤100k	ONNX (CPU)
Linux / WSL	none / intel	>100k	Ollama (CPU)
Windows	nvidia	any	ONNX (DirectML) or Ollama (CUDA)
Windows	amd (RDNA2/3)	any	ONNX (DirectML) or Ollama + PRO driver
Windows	amd/intel/none	any	ONNX (DirectML or CPU)

Install Ollama + pull the default model

# macOS / Linux / WSL
curl -fsSL https://ollama.com/install.sh | sh

# Windows (winget)
winget install Ollama.Ollama

Pull the default code-embedding model (~270 MB):

ollama pull unclemusclez/jina-embeddings-v2-base-code:latest

Verify: curl -s http://localhost:11434/api/tags lists the model.

AMD on Windows (RDNA2 / RDNA3): install the AMD Radeon PRO driver before Ollama for GPU acceleration.

Use ONNX (built-in, no install)

No install needed. At Step B.4, register the MCP server with -e EMBEDDING_PROVIDER=onnx. ONNX runs inside the MCP process — no Ollama, no Docker. Best for Windows (DirectML GPU) and projects up to ~100k LOC on CPU.

Use OpenAI / Cohere / Voyage (cloud)

No local install. At Step B.4, register with the provider and key:

-e EMBEDDING_PROVIDER=openai  -e OPENAI_API_KEY=sk-...
# or
-e EMBEDDING_PROVIDER=cohere  -e COHERE_API_KEY=...
# or
-e EMBEDDING_PROVIDER=voyage  -e VOYAGE_API_KEY=...

B.4. Register the MCP Server

For Claude Code — env vars are claude mcp add flags, so they go before --:

# Ollama (defaults — Qdrant embedded, Ollama on localhost:11434)
claude mcp add tea-rags -s user -- tea-rags

# ONNX
claude mcp add tea-rags -s user \
  -e EMBEDDING_PROVIDER=onnx \
  -- tea-rags

# OpenAI
claude mcp add tea-rags -s user \
  -e EMBEDDING_PROVIDER=openai \
  -e OPENAI_API_KEY=sk-... \
  -- tea-rags

For other MCP clients (Cursor, Roo Code, Continue, …), add this to your mcpServers JSON config:

{
  "mcpServers": {
    "tea-rags": {
      "command": "tea-rags",
      "env": {
        "EMBEDDING_PROVIDER": "onnx"
      }
    }
  }
}

Qdrant starts automatically (embedded). For external Qdrant or Qdrant Cloud, see Connect to an Agent.

B.5. (Claude Code only) Install the skills plugin

Once the MCP server is registered, install the skills plugin to get /tea-rags:* slash-commands:

/plugin marketplace add artk0de/TeaRAGs-MCP
/plugin install tea-rags@tea-rags

Next Steps

Connect to an Agent — remote Qdrant, Qdrant Cloud, HTTP transport, provider overrides
Create Your First Index — index a codebase
Skills — playbooks the skills plugin activates

Keeping up to date

When a newer version of tea-rags is published, run:

tea-rags update

This pulls the latest version from npm. The tea-rags prime command also surfaces a notice when a new version is available — see Keeping tea-rags up to date for the full mechanics.

Build from Source (contributors)

For contributing to TeaRAGs itself

git clone https://github.com/artk0de/TeaRAGs-MCP.git
cd TeaRAGs-MCP
npm install && npm run build
claude mcp add tea-rags -s user -- node "$PWD/build/index.js"

Then install an embedding provider per B.3. Qdrant auto-starts (embedded). This path is for contributing to TeaRAGs itself — end users should use npm install -g tea-rags instead.

Option A — via the Setup Plugin (Claude Code, recommended)​

Option B — Manual Install​

B.1. Install Node.js 24+​

B.2. Install tea-rags​

B.3. Pick an Embedding Provider​

B.4. Register the MCP Server​

B.5. (Claude Code only) Install the skills plugin​

Next Steps​

Keeping up to date​

Build from Source (contributors)​