Ratel Local

Name: Ratel Local
Author: Ratel

Local MCP gateway that hides upstream tool schemas behind one capability search

By Ratel TypeScript Local · stdio Developer tools

GitHub npm Website

30 popularity score ★ 16 ↓ 83/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

Claude CodeTerminal

claude mcp add ratel-local -- npx -y @ratel-ai/ratel-local serve --auto-config --project-root '<ABSOLUTE_PATH_TO_PROJECT>'

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "ratel-local": {
      "command": "npx",
      "args": [
        "-y",
        "@ratel-ai/ratel-local",
        "serve",
        "--auto-config",
        "--project-root",
        "<ABSOLUTE_PATH_TO_PROJECT>"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "ratel-local": {
      "command": "npx",
      "args": [
        "-y",
        "@ratel-ai/ratel-local",
        "serve",
        "--auto-config",
        "--project-root",
        "<ABSOLUTE_PATH_TO_PROJECT>"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "ratel-local": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ratel-ai/ratel-local",
        "serve",
        "--auto-config",
        "--project-root",
        "<ABSOLUTE_PATH_TO_PROJECT>"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.ratel-local]
command = "npx"
args = ["-y", "@ratel-ai/ratel-local", "serve", "--auto-config", "--project-root", "<ABSOLUTE_PATH_TO_PROJECT>"]

Gemini CLITerminal

gemini mcp add --scope user ratel-local npx -- -y @ratel-ai/ratel-local serve --auto-config --project-root '<ABSOLUTE_PATH_TO_PROJECT>'

Settings 6

`RATEL_PROJECT_ROOT`	Optional: Project folder whose project and local configuration is loaded when --project-root is not given.
`RATEL_TELEMETRY`	Optional: Set to off to stop writing local per-session telemetry files.
`RATEL_API_KEY`	Optional: Ratel Cloud key for the experimental trace export.
`RATEL_FEATURE_ADAPTIVE_RANKING`	Optional: Set to 1 to enable experimental ranking that learns from past searches.
`RATEL_FEATURE_CLOUD_CATALOG`	Optional: Set to 1 to add skills from Ratel Cloud to the catalog.
`RATEL_FEATURE_CONNECTOR_RECOVERY`	Optional: Set to 1 to let the connector reattach after the daemon is interrupted.

What it does

Ratel Local sits between a coding agent and the MCP servers it already uses. Instead of loading every upstream server's tool definitions into the prompt, the agent sees a few gateway tools: it searches a combined catalog of upstream tools and skills, then calls the chosen tool through the gateway. Upstream schemas and skill text only reach the context when a search returns them.

Upstreams are added with the `ratel-local mcp add` command at user, project or local scope, and can be stdio servers or remote HTTP/SSE servers, including ones that sign in with OAuth (tokens are kept under ~/.ratel/oauth/). Search uses BM25 by default; semantic and hybrid retrieval can be switched on per scope with a local, Hugging Face, Ollama or OpenAI-compatible embedding source. For Claude Code and Codex a `setup` wizard installs a background daemon and links the agent; Cursor and other clients run `ratel-local serve --auto-config` directly, which needs no daemon.

In `serve --auto-config` mode the project root is taken from `--project-root`, then the RATEL_PROJECT_ROOT variable, then CLAUDE_PROJECT_DIR, then a search up from the working directory; if none is found only the user configuration is loaded. The same handler writes a JSONL telemetry file per session to a local telemetry folder unless `--telemetry off` or RATEL_TELEMETRY=off is set (serve.ts at v0.9.0).

What it needs

Runtime	Node.js 20+

Node.js 20.6 or newer (npx). The upstream MCP servers you want behind it, added with `ratel-local mcp add`. The setup wizard and `link` only adapt Claude Code and Codex; Cursor is configured by hand in mcp.json. A Ratel Cloud key is needed only for the optional Cloud skill catalog or telemetry.

Limits

It adds no capabilities of its own: what it can do is what the upstream servers you configure can do. `import` and `link` do not support Cursor, and Cursor's existing MCP entries are not migrated automatically. `serve` exits unless given `--auto-config` or a config file path. Adaptive ranking, Cloud telemetry and the Cloud skill catalog are experimental and off by default, each enabled only by setting its RATEL_FEATURE_ flag to exactly 1. `get_skill_content` appears only when at least one skill is loaded. After changing retrieval settings the agent must reconnect.

Who it suits

Developers who run many MCP servers in Claude Code, Codex or Cursor and want to keep tool schemas out of the prompt, accepting one extra search step before each tool call. With only one or two upstream servers, connecting them directly is simpler. Because every upstream's credentials and tool calls pass through it, pick it only if you are comfortable running a local gateway process (and, for Claude Code and Codex, a per-user daemon) on your machine. Teams wanting the catalog inside their own agent code are pointed by its docs to the Ratel SDKs instead.

Tools 4

search_capabilities: Searches the combined catalog of upstream tools and skills and returns the best matches
invoke_tool: Calls a chosen upstream tool through the gateway with the given arguments
get_skill_content: Loads the instructions of a skill; present only when skills are configured
auth: Starts authorization for an upstream server that needs OAuth sign-in

Popularity

30 popularity score

★ 16 ↓ 83/wk

GitHub stars, whole repository	16	14.8 points
npm downloads, last week	83	15.4 points

It lives in the folder apps/ratel-local of ratel-ai/ratel-local, which holds more than this server. Its stars are the whole repository's, so in the score they never count for more than its own downloads.

Measured 2026-11-07. How the score works.

Where it is published

Code	ratel-ai/ratel-local/apps/ratel-local ★ 16, the whole repository
npm	@ratel-ai/ratel-local 0.9.0, 2026-09-04

What it can reach

Runs	On your machine
Reaches	The internet, Files on your machine, Runs shell commands
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	MIT (npm)
Last code change	2026-10-09

Runs on your machine. It starts the stdio upstream servers named in its configuration as local processes and connects to remote HTTP/SSE upstreams over the network; `invoke_tool` passes calls to any of them, so it can write or delete whatever those upstreams can. OAuth tokens are stored under ~/.ratel/oauth/ (directory mode 0700, files 0600 where supported); a static `--client-secret` is saved as plain text in Ratel config and its backups. Local telemetry JSONL files are written per session by default. Experimental adaptive ranking stores raw search queries under ~/.ratel/adaptive-ranking/. Cloud features send data to Ratel Cloud only when their flags are set to 1.

Over time

GitHub stars, whole repository 16 +2 (+14 %)

1614

14 Oct 20267 Nov 2026

npm downloads a week 83 −225 (−73 %)

5020

27 Jul 20267 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 30 +7 (+32 %)

310

14 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![Ratel Local on EveryMCPServer](https://everymcpserver.com/badge/ratel-local.svg)](https://everymcpserver.com/servers/ratel-local)

Connect your client

Add in one click

Or add it by command or config

Settings 6

What it does

What it needs

Limits

Who it suits

Tools 4

Similar servers

SDL-MCP

Quill

mcptoon

cclsp

1MCP

agent-harnesses MCP server