Serena

IDE-style "find symbol" and "edit symbol" for an agent, backed by language servers.

Started in our test
★ 30.7K GitHub stars
47.5K downloads a week
Last commit 26 Oct 2026

At a glance

Serena starts language servers for your project and exposes what they know: where a function is defined, who calls it, and the exact range of a class or method. The assistant can then read and edit by symbol instead of grepping and reading whole files.

On big repositories that saves a lot of context, and it makes edits land in the right place more often.

Made by: Oraios AI
GitHub stars: 30.7K
Downloads: 47.5K a week
Last commit: 26 Oct 2026
Tools: 3
Runs on: Your computer

Our check: We ran this exact config on 26 Oct 2026: it started and answered with 3 tools. The npm package called "serena" has no link to this project. Serena publishes to PyPI as serena-agent and documents running it from the GitHub source with uvx, which is what the config here does.

What's in the pod: its tools

We found 3 tools when we started it on 26 Oct 2026. 2 only read. The rest can change things, so keep your app's "ask before each tool call" setting on for them.

Changes things1 tool · Can create, edit, send or delete.

Tool	What it is for
`serena_repl`	Runs Python with Serena's full toolkit loaded: find symbols and references, outline files, edit by symbol and refactor.

Only reads2 tools · Looks things up and changes nothing.

Tool	What it is for
`activate_project`	Points Serena at a codebase by name or folder so its language servers start indexing it.
`initial_instructions`	Hands the agent Serena's how-to guide and a session id at the start of a chat.

Grouped and described by us. The README on GitHub lists the inputs each tool takes.

Set it up

Pick your app for the exact snippet and where it goes.

Where it goes: claude_desktop_config.json (Settings → Developer → Edit Config)

Claude Desktop

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server"
      ]
    }
  }
}

Where it goes: Your terminal, in the project folder

Claude Code

claude mcp add-json serena '{"command":"uvx","args":["--from","git+https://github.com/oraios/serena","serena","start-mcp-server"]}'

Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

Cursor

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server"
      ]
    }
  }
}

Where it goes: .vscode/mcp.json in your project

VS Code

{
  "servers": {
    "serena": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server"
      ]
    }
  }
}

Where it goes: ~/.codeium/windsurf/mcp_config.json

Windsurf

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server"
      ]
    }
  }
}

New to this? See the setup guides for Claude Code, Cursor, Claude Desktop and ChatGPT.

Settings

Names are exactly as the project spells them. Required ones are marked.

Setting	What it does
`serena init`Config · required	One-off setup that checks your install and picks the backend. Add -b JetBrains to use the paid IDE plugin instead of language servers.
`--context`Command line flag	Tunes the tool set for where Serena runs. A coding harness like Claude Code needs fewer of its basic file tools than a plain chat app.`--context claude-code`
`--project`Command line flag	Opens a project at launch so you can skip activate_project.`--project /path/to/repo`
`--transport`Command line flag	Run over stdio (default) or as an HTTP server you connect to by URL.`--transport streamable-http`
`.serena/project.yml`Config	Per-project settings such as the languages to index and tools to hide. Created the first time a project is activated.

What it can touch

It can read

Source files in the project you activate, through language servers or your JetBrains IDE
Its own memory notes saved in the project's .serena folder

It can change

Your code, when it replaces, inserts, renames or deletes symbols
Memory files it writes for later sessions
Shell commands, if its basic tools are switched on

Safer setup: Run it inside a git repository so every edit shows up in the diff, and leave the shell tool disabled when your client already has one.

Before you start

uv (for uvx)
Language support for your project language (Serena downloads most servers itself)

If it does not work

Symbols are not found in some languages: A few languages need their language server installed separately. Check Serena's language support page for the one you use.
Installed from a marketplace and nothing works: The project warns that marketplace entries carry old commands. Install with uv tool install -p 3.13 serena-agent, then run serena init.
The agent ignores Serena and greps instead: Ask it to call initial_instructions first, or name the project so it activates Serena before searching.

Peas in a pod: similar servers

How Serena lines up against other developer tools servers on the shelf.

Server	Tools	Runs on	Licence	Stars
Serena	3	Your computer	–	30.7K
Context7	2	Your computer or hosted	MIT	63.7K
GitHub	46	Hosted	–	34K
MCP Inspector	–	Your computer	–	11.2K
XcodeBuildMCP	24	Your computer	MIT	6.5K