cqbase.net · English & Chinese

CQBase

Context & Query Base

MCP

Serena

An MCP toolkit for coding agents, focused on semantic retrieval and editing. The license is unspecified.

oraios/serena is described as an MCP toolkit for coding agents, with semantic retrieval and editing. The repository compares it to an IDE for the agent. GitHub does not map the license to a clear SPDX identifier.

Try it on a small repository, see which symbols it indexes and how wide an edit can be, then connect it to a daily coding agent. The license is unspecified, so decide commercial use yourself. Do not point it at code you are not allowed to change.

Mentioned by:

  • @HermesWatcher mentioned this project on 27 October 2026 (1149 likes and 126 reposts, captured 15 November 2026).
  • @stewy0x mentioned this project on 14 November 2026 (52 likes and 7 reposts, captured 15 November 2026).
  • @skizzyy2 mentioned this project on 12 November 2026 (20 likes and 0 reposts, captured 15 November 2026).

This page is a guide, not the original text.

What problem it solves

Serena (repository oraios/serena) is an MCP toolkit for coding agents. It focuses on retrieving, editing, and refactoring code at the symbol level. Official docs compare it to an IDE for the agent. By default it understands code through language servers (LSP). A paid JetBrains plugin is an optional backend, with a free trial.

Serena does not replace the model. It adds tools to an MCP client you already use. Official client coverage includes Claude Code, Codex, Claude Desktop, and IDEs such as VS Code, Cursor, and JetBrains. The README also mentions a new REPL-based agent interface in v2. This page covers only the MCP path.

Who it is for

It is for people who already use a coding agent and want it to find and change code by symbol, not by line number. Official docs say the language-server backend supports more than 40 languages; see Language Support for the list and any extra dependencies.

Try it on a small repository first. See which symbols it indexes and how wide an edit can be, then connect it to daily work. Do not point it at code you are not allowed to change. This catalog records the license as unspecified; see Sources and license at the end of this page.

How to install it

Checked on 15 November 2026 (Asia/Shanghai) against the repository README and the official Connecting Your MCP Client guide.

Official docs warn, prominently, not to install Serena from an MCP or plugin marketplace, because those commands are often outdated or a poor fit. The only prerequisite is uv. Then run:

uv tool install -p 3.13 serena-agent

After a successful install, the serena command should be available in your shell. Initialise it with:

serena init

That sets up the language-server backend by default. To use the JetBrains backend instead, official docs add -b JetBrains and point you to the plugin page.

If a client cannot find the serena command, even when it is on your system PATH, official docs suggest putting the absolute path to the executable in the config. Some language servers also need extra environment variables. Clients such as Claude Desktop may not inherit variables from your shell profile; add them under the env key of the MCP entry.

Claude Code

Official docs provide a shortcut, serena setup claude-code. For a manual user-level install:

claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd

For the current project only:

claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"

Confirm the connection with /mcp. If Serena is slow to start, official docs suggest raising MCP_TIMEOUT, for example by adding export MCP_TIMEOUT=60000 to your shell profile. They also strongly recommend reminder hooks to reduce cases where Claude Code ignores Serena’s tools or drifts mid-session. Those hooks are marked alpha; details are in the client guide. This page does not treat hooks as a required install step.

Cursor

Official docs group Cursor with Cline, Windsurf, and similar MCP-enabled IDEs, and recommend --context ide to reduce overlap with the editor’s built-in tools. They do not give a Cursor-specific JSON file path. When you add a stdio server in Cursor’s MCP settings, the command is serena and the arguments are:

start-mcp-server --context ide

If Cursor cannot find the command, use the absolute path to serena.

Claude Desktop

Edit claude_desktop_config.json from Settings → Developer:

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": ["start-mcp-server", "--context=desktop-app"]
    }
  }
}

Official docs say you must fully quit Claude Desktop with File / Exit; closing the window often only minimizes it. After a restart, Serena’s tools should appear in the chat UI (the hammer icon). Claude Desktop uses a global config, so you usually need to ask the agent to activate the project first, for example “Activate the current dir as project using serena.”

A worked example

The prompt below is a check written for this page, not a canned official phrase. It was not run on a live repository, so this page does not invent a symbol list.

  1. Run serena init in a small, disposable repository, and connect the client as above.
  2. If the client uses a global config, first send: Activate the current directory as a Serena project. Do not edit any files.
  3. Then send: Using Serena, find the definition of <a symbol you name> and list its references. Do not rename or replace anything.
  4. Check the result against jump-to-definition in your editor. If the agent only uses built-in text search and never calls Serena, read the official client notes, especially the Claude Code section on hooks and tool preference.

Common pitfalls

  • Installing from an MCP or plugin marketplace. The official README marks this as an important warning and calls those commands outdated or a poor fit. Use uv tool install as above.
  • The client cannot find serena. Official docs list “use the absolute path” as a common workaround.
  • In Claude Code, the agent often skips Serena’s symbol tools. Official docs attribute part of this to the client’s tool discovery and to a bias toward built-in tools. They offer hooks and serena prompts print-cc-system-prompt-override. Issue #2251 (still open on 15 November 2026) also reports that serena-hooks remind can block a tool call instead of only reminding. If you enable hooks, read the current docs and watch the actual behavior.
  • Startup timeouts. Official docs mention raising MCP_TIMEOUT. Issue #2270 (still open) also records activation-command timeouts over stdio on Windows.
  • Edits that are wider than you intended. Symbol replacement, rename, and delete change real files. Learn the tools on a small repository before you use them on a daily branch.

FAQ

Do I have to install the JetBrains plugin?

No. The default backend is language servers, which official docs describe as the free, open-source path. The JetBrains plugin is a paid option with a trial, and it adds capabilities the language-server backend does not have, including some refactors and interactive debugging. Official docs say Rider and CLion are unsupported.

Why does the official command pin Python 3.13?

The current README install command is uv tool install -p 3.13 serena-agent. This page did not find a conflicting minimum version on another official page. Follow that command as written, rather than substituting a version the docs do not name.

What is the license?

This catalog records it as unspecified, because GitHub does not map the repository to a single SPDX identifier. Official docs describe a per-component arrangement. Read the repository LICENSE and the license documentation. This page only summarizes and links. Decide for yourself before commercial use or redistribution.

Should Cursor use --context ide?

That is the official recommendation for Cursor and similar IDE clients, to reduce duplicate tools. The docs do not also give a complete Cursor-only JSON example. If tools look duplicated or missing, check the context flag in the launch arguments first.

What is the difference between a global config and a project config?

Official docs draw a clear line. Clients with per-workspace config, such as VS Code and Claude Code, should usually start with the project directory and not switch projects mid-session. Clients with a global config, such as Claude Desktop, need the project to be activated first, and the activate_project tool is required.

Sources and license

The license for oraios/serena is recorded as unspecified in this catalog. Official documentation is in LICENSE and the license page. This page follows the README and the client setup guide as of 15 November 2026, rewritten for CQBase — Context & Query Base. If the install command or client arguments change, follow those official pages.

Subscribe to CQBase Weekly

One email a week with newly catalogued public AI skills, prompts, MCP servers, and methods. Unsubscribe at any time. We will not hand your address to a third party for their marketing.