oraios/serena

⭐ 24,033  ·  Python  ·  GitHub Repo

A powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent

agent ai ai-coding claude claude-code codex ide jetbrains

1-Sentence Summary

Agent-first MCP toolkit giving AI coders IDE-level semantic code understanding and refactoring superpowers.

🔥 Key Capabilities & USP

• Semantic Code Retrieval – Agents can find symbols, references, type hierarchies, and file outlines without reading entire files. This eliminates the token waste and fragility of pattern-matching or line-number-based approaches in large codebases.
• Precise Refactoring – Atomic rename, move, inline, and delete propagation operations that are safe and correct. This solves the critical pain point of fragile search-and-replace that plagues naive agent coding.
• Symbolic Editing – Token-efficient replace, insert before/after, and safe delete of symbol bodies. Reduces both error rates and token costs dramatically compared to editing raw text.
• Memory System – Built-in persistent memory for long-lived agent workflows, enabling agents to maintain context across sessions without manual re-prompting.
• Interactive Debugging (JetBrains Plugin) – Debugging capabilities integrated directly into the agent workflow, a rare and powerful feature for agent-assisted development.

USP: Serena is the first tool designed from the ground up for agents, not humans. It provides high-level abstractions (symbols, references, refactorings) instead of primitive operations (line numbers, regex patterns), making it uniquely effective for complex, multi-file codebases.

Technical Architecture

Component	Description
Protocol	Model Context Protocol (MCP) server – connects to any MCP-compatible AI client (Claude Code, Codex, Cursor, JetBrains)
Backend 1	Language Server Protocol (LSP) – free, open-source, supports 40+ languages
Backend 2	Serena JetBrains Plugin – paid plugin leveraging JetBrains IDE's deep analysis engine for advanced refactoring and debugging
Deployment	CLI command (npx @serena/serena) or HTTP mode for remote/containerized setups
Language	Python (server), with Node.js CLI wrapper for easy installation

Quick Start Guide

Install and run Serena as an MCP server for your AI client:

# Install globally via npm
npm install -g @serena/serena

# Launch the MCP server (connects to your AI client via stdio)
serena

For HTTP mode (remote/containerized setups):

serena --http

Important: Do not install via MCP/plugin marketplaces – those contain outdated instructions. Always use the official npm package.

Pros, Cons & Use Cases

Pros

• Agent-first design – high-level abstractions (symbols, references) instead of fragile line numbers or patterns
• Massive language support – 40+ languages via free LSP backend
• Client-agnostic – works with any MCP-compatible AI client (Claude Code, Codex, Cursor, Copilot CLI, etc.)
• Proven effectiveness – evaluated with Opus 4.6 and GPT 5.4 across multiple codebases
• Token-efficient – symbolic editing dramatically reduces token consumption vs. full-file reads

Cons

• JetBrains Plugin is paid – advanced features (move, inline, debug) are exclusive to the paid plugin (free trial available)
• LSP backend limitations – limited external dependency navigation and some refactoring operations
• Rider & CLion unsupported – JetBrains users on these IDEs cannot use the plugin
• Installation gotcha – outdated instructions on marketplaces; must use official npm package

Who should NOT use this?

• Simple script or toy project developers – if your codebase is small (<10 files) or single-file, the overhead of setting up an MCP server isn't justified
• Developers not using AI coding agents – this tool is useless without an MCP-compatible AI client
• JetBrains Rider/CLion users – the advanced plugin doesn't support these IDEs, and the LSP backend may be insufficient for your needs

Ideal Use Cases

• Large, complex codebases (100k+ LOC) where semantic understanding saves massive token costs
• Multi-file refactoring workflows – renaming symbols, moving code, or propagating changes across files
• Agent-assisted development pipelines – CI/CD agents, code review agents, or long-running refactoring agents
• Teams using Claude Code, Codex, or Cursor who want to give their agents IDE-level capabilities

Community & Activity

With 24,033 stars and active development through May 2026, Serena has clearly struck a nerve in the AI coding community. This isn't a side project – it's a rapidly maturing tool with serious traction. The combination of an enthusiastic open-source community (LSP backend) and a commercial offering (JetBrains Plugin) suggests a sustainable development model. The project is actively maintained, with the latest update just days ago, and the ecosystem of MCP-compatible clients continues to grow, making Serena an increasingly valuable piece of the AI coding stack.