Third-party toolUpdated 2026.11.16

Serena MCP on Windows: Connect Codex and Claude Code, Then Trace a Bug

Set up Serena MCP on Windows, trace a function and its callers, replace only the target symbol and verify the change with five Python regression checks.

Aaron recommends Open official GitHub

Serena gives a coding assistant symbol lookup, definitions and reference search through MCP. Add it when you work in an existing codebase and need to understand callers before making a change. For a short script or a simple text search, your assistant's built-in tools may already be enough.

This walkthrough uses a small sales calculation to make the connection observable: Codex must retrieve the function and its caller through Serena, then change only that function and run five regression checks.

Install a project-local executable

Start in an empty project directory with uv installed. You also need Codex CLI or Claude Code. In PowerShell:

uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe serena-agent==2.1.0 jedi-language-server==0.47.0
$serena = (Resolve-Path .venv\Scripts\serena.exe).Path
$project = (Get-Location).Path
$env:PATH = "$project\.venv\Scripts;$env:PATH"
& $serena start-mcp-server --help

The help output includes --project, --context and --agent-interface. The PATH line matters too: Serena starts jedi-language-server by name. Registration below explicitly passes that PATH to the MCP process so both programs use the same environment.

Create .serena/project.yml and select Jedi for this Python example:

project_name: sales-project
language_servers: [python_jedi]

Create sales.py:

def total_sales(amounts):
    return sum(amounts)

def report():
    return total_sales([120, 80])

Suppose the requirement is to ignore negative adjustments. This implementation returns 190 for [120, 80, -10]. Leave it unchanged so the assistant has a real discrepancy to investigate.

Register Serena with Codex CLI

Use the same PowerShell session so the two variables remain available:

codex mcp add serena --env "PATH=$env:PATH" -- $serena start-mcp-server --context codex --project $project --agent-interface tools --enable-web-dashboard false --enable-gui-log-window false
codex mcp list

The list should contain serena and the launch command. Start a fresh Codex conversation in the project and try the prompts below. Look for calls to Serena's get_symbols_overview or find_symbol; those are the useful confirmation that the assistant used the connection.

Keep --agent-interface tools for this walkthrough. Serena 2 also supports a REPL interface, which exposes operations differently.

Register it with Claude Code

From the project directory:

claude mcp add serena --scope project --transport stdio --env "PATH=$env:PATH" -- $serena start-mcp-server --context claude-code --project $project --agent-interface tools --enable-web-dashboard false --enable-gui-log-window false
claude mcp list

The health check should show Serena as connected. Our run displayed ✓ Connected. Project scope stores the entry in .mcp.json, where you can inspect its executable and project paths.

For Cursor, use the upstream client guide and its ide context.

Three jobs to try

Find a definition without opening the whole file

Use Serena. Read initial_instructions, request get_symbols_overview for sales.py,
then use find_symbol to retrieve only total_sales with its body.
List the discovered functions. Do not edit files or run shell commands.

The overview contains total_sales and report. The selected body shows return sum(amounts). On a larger file, this sequence helps narrow the material the assistant needs to read.

Identify the caller before changing an interface

Use Serena's find_referencing_symbols for total_sales in sales.py.
Report the calling function and the call expression. Explain what would need
checking if total_sales changed its input type. Keep the task read-only.

The reference belongs to report, which calls total_sales([120, 80]). That positive-only example is a useful regression case when changing the calculation rule; a signature change would also require reviewing the caller.

Edit the definition and verify the rule

Use Serena to inspect total_sales and its references in sales.py.
The requirement is to ignore negative adjustments. Use replace_symbol_body
to change only total_sales, then read it back with find_symbol. Preserve report.
Run Python locally to check mixed values, positive values, an empty list,
negative-only values and report.

Our replacement returned OK. Reading it back showed:

def total_sales(amounts):
    return sum(amount for amount in amounts if amount >= 0)

Run the regression checks from the project terminal:

.venv\Scripts\python.exe -c "from sales import total_sales, report; assert total_sales([120,80,-10])==200; assert total_sales([120,80])==200; assert total_sales([])==0; assert total_sales([-10])==0; assert report()==200; print('PASS: all 5 assertions')"

All five passed. The mixed input changed from 190 to 200 while the positive-only caller still returned 200. Ignoring negatives is this example's explicit business rule; establish the correct accounting behavior before applying such a change to real data.

Serena reports zero-based line positions. Account for that when comparing its result with an editor's displayed line numbers.

Troubleshooting

Serena works in a terminal but the client cannot start it

Check that the registered command contains the full path to .venv\Scripts\serena.exe. A client launched elsewhere may have a different PATH. Resolve the executable inside the environment where you installed the packages.

The server connects, but symbol lookup is empty

Check the project path, the python_jedi setting and the installed Jedi package. If you see LanguageServerTerminatedException, verify that the registered --env value includes the venv's Scripts directory in PATH. Our independent reproduction failed when that PATH entry was missing. Other languages have their own prerequisites in the upstream guide.

The expected tools are missing

Check --agent-interface tools and reconnect after changing the launch arguments. In Serena 2's REPL interface, individual operations are not exposed in the same way. A different tool list can reflect an interface choice rather than a failed connection.

An edit reports “MCP tool call requires approval, but approval policy is never”

An earlier read-only session rejected the replacement and left the file unchanged. Check which editing and command operations your project permits, then start a fresh session. In our disposable project, a session permitting those operations completed the replacement and tests. Reinstalling Serena does not change client policy.

Where Serena fits

Reference discovery depends on the language server's understanding of the program. Dynamic imports and names assembled from strings can require additional text searches and tests. This small example provides no basis for predicting indexing time or token savings on a large repository.

The local open-source server has no separate model API charge. Your AI client and model usage remain separate, and the optional JetBrains backend has its own pricing. The Serena application is GPL-3.0-or-later; SolidLSP is MIT-licensed. Set SERENA_USAGE_REPORTING=false in the server environment to opt out of startup usage reporting.

For TODOs and fixed strings, use your existing search first. For packaging a repository to share with another conversation, see Repomix. Serena's useful addition here is the relationship between a definition and its calling symbols.

FAQ

What does Serena MCP do?

It exposes code navigation and operations to an AI client using symbols and references. You can ask the assistant to identify a problematic definition and its callers before deciding what to change. The tool provides structural evidence; requirements and correctness still need developer judgment and tests.

Can I use Serena with both Codex and Claude Code?

Yes. Use the codex context for Codex and claude-code for Claude Code. The commands above bind one project explicitly, so check --project when moving to another codebase.

Is Serena useful if my assistant already has grep?

Grep finds matching text. Serena can return the enclosing calling symbol, such as report in this example, which helps when tracing the impact of a change. For a small script or a literal text search, the existing search tool is often sufficient.

Why does the assistant ignore Serena after connecting?

An available tool is still a choice the model must make. Name the desired operation, file and symbol explicitly, then inspect the recorded calls. Upstream also documents optional hooks for persistent tool-use problems once basic setup works.

References

What we tested

On 2026-11-16: Windows, Python 3.12, Serena 2.1.0, Jedi language server 0.47.0 and Codex CLI 0.169.0. Codex used the actual symbol, definition and reference tools to investigate the sales calculation; Claude Code add/list reported Connected. The added editing test used replace_symbol_body, read the result back and passed five Python assertions: mixed, positive, empty, negative-only and report. Cursor, other languages and large repositories were not tested.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Or follow us on: