Serena: A Free MCP Tool for Semantic Retrieval and Editing Code

General Introduction

Serena is a free and open source programming tool developed by the Oraios AI team and hosted on GitHub. It is a powerful code assistant that works directly in your codebase to help developers analyze, edit, and execute code.Serena implements semantic analysis through the Language Server Protocol (LSP) to quickly understand code structure. It also integrates with large language models (LLMs) such as Claude or other free models without additional subscription fees.Serena was originally designed to free developers from expensive tool dependencies and provide practical, efficient programming support. It is suitable for individual developers, small teams, and even large projects.

Function List

• Semantic search: find symbols, references or definitions based on the meaning of the code.
• Code editing: Support inserting, replacing and deleting code blocks with precise operation.
• Command Execution: Run a test or script in your project and see the results.
• Project Overview: Displays a summary of the directory structure and file contents.
• Multi-language support: direct support for Python, Java, TypeScript, indirect support for more languages.
• Memory storage: Save analysis records for subsequent use.
• LLM Integration: via MCP maybe Agno The framework works with the language model.
• Open source and free: no API key or payment is required to use it.

Using Help

The installation and use of Serena requires a few steps, but overall it is not difficult. The following is a detailed description of how to install, configure, and operate its core functions.

Installation process

1. Checking the environment
   Serena requires Python 3.11. Open a terminal and type:

python --version

If you have a version lower than 3.11, go to the Python website to download and install it.

2. Download Project
   Go to https://github.com/oraios/serena and click on "Code" to copy the HTTPS link. Run it in a terminal:

git clone https://github.com/oraios/serena.git

The project will be downloaded locally.

3. Installation tools uv
   Serena uses uv to manage dependencies. To install uv refer to: https://docs.astral.sh/uv/getting-started/installation/. Run it on Linux/macOS for example:

curl -LsSf https://astral.sh/uv/install.sh | sh

4. Installation of dependencies
   Go to the project catalog:

cd serena

Install basic dependencies:

uv pip install -e .

If you want to use the Agno framework, install all the dependencies:

uv pip install --all-extras -e .

5. Configuration items
   Copy the sample configuration file:

cp myproject.demo.yml myproject.yml

compiler myproject.yml, setup:

• project_root: Your code path, e.g. /home/user/mycodeThe
• language: Language type, e.g. pythonThe
• ignored_dirs: Ignore folders such as .gitThe
  Save the file.

activation method

Serena supports two main types of usage: the MCP server and the Agno framework.

MCP Server (with Claude Desktop)

1. Installing Claude Desktop
   Download at https://claude.ai/download for Windows and macOS.
2. Configuring MCP
   Open Claude Desktop, go to "File > Settings > Developer > MCP Servers > Edit Config", edit the claude_desktop_config.json, add:

{
"mcpServers": {
"serena": {
"command": "/path/to/uv",
"args": ["run", "--directory", "/path/to/serena", "serena-mcp-server", "/path/to/myproject.yml"]
}
}
}

commander-in-chief (military) /path/to/uv cap (a poem) /path/to/serena Replace with the actual path.Windows users note the double backslash (\).

3. activate (a plan)
   Save and restart Claude Desktop. the interface will show the Serena tool (with the small hammer icon).

Agno framework

1. Installing the UI
   Download Agno UI:

   npx create-agent-ui@latest
   

   or manual cloning:

   git clone https://github.com/agno-agi/agent-ui.git
   cd agent-ui
   pnpm install
   pnpm dev
   

2. Configuration environment
   In the Serena directory, copy .env.example because of .envIf you are using a paid model, fill in the API key (if you are using a paid model).
3. Start Agno.
   Run in the Serena catalog:

   uv run python scripts/agno_agent.py
   

   Claude is used by default and can be changed to other models in the script.

4. Connecting the UI
   Open the Agno UI in your browser (usually http://localhost:5173) and connect to the Agno agent.

Core Function Operation

semantic retrieval

Trying to find a reference to a certain function:

1. Enter a request in the Claude or Agno interface, such as "Find my_function of the citation."
2. Serena, call. find_symbolthat returns the function definition and reference location.

code editor

Insert new code:

1. expense or outlay read_file View Document:

   read_file path/to/file.py
   

2. expense or outlay insert_at_line Insert, for example, add code to line 5:

   insert_at_line path/to/file.py 5 'print("Test")'
   

3. Check the file to confirm the changes.

Run command

Run the test:

1. Input:

   execute_shell_command 'pytest tests/'
   

2. Serena executes and returns the result. If something goes wrong, it suggests a fix.

Featured Function Operation

Project Overview

Quickly understand the code structure:

1. Input:

   get_dir_overview
   

2. Serena returns the files and top-level symbols in the directory.

Automated analysis and recommendations

Analyzing the problem:

1. After running the test with think_about_collected_information::

   think_about_collected_information
   

2. Serena suggests fixes based on logs or output.

caveat

• pathway issue: Use absolute paths to avoid relative path errors.
• safety: Agno mode.execute_shell_command No confirmation is required. Handle with care.
• log (computing): Enable the logging window (in the myproject.yml investment management show_logs: true) for easy debugging.
• version control: It is recommended that you manage your code in Git to prevent accidental loss.

With these steps, you can easily use Serena and improve your programming efficiency.

application scenario

1. Fast Bug Fixes
   When the test fails, Serena runs the script, analyzes the logs, and suggests code changes suitable for an emergency fix.
2. Learning open source projects
   Use Serena to analyze unfamiliar codebases and generate structural overviews to quickly grasp the core logic.
3. prototyping
   Individual developers use Serena to insert code, run tests, and quickly validate ideas.

QA

1. Is Serena completely free?
   Yes, it's open source and requires no subscription. Use it in conjunction with a free LLM such as Claude Free Edition.
2. What languages are supported?
   Direct support for Python, Java, TypeScript. indirect support for Ruby, Go, C# (manual configuration required, not fully tested).
3. How do you handle big projects?
   Serena analyzes code efficiently with LSP. Recommended configuration ignored_dirs Ignore extraneous folders.