1. Home
  2. Serena
  3. Serena for Claude Desktop: Setup & Config

Data as of

Serena for Claude Desktop: Setup & Config

Serena gives Claude Desktop symbol-aware retrieval, editing, refactoring, and debugging capabilities through MCP.

What you can do with Serena in Claude Desktop

Add symbol-aware IDE capabilities to coding agents instead of relying entirely on text search and edits.

  • Navigate a large project using symbols, references, and file outlines.
  • Edit symbol bodies and perform backend-supported refactorings.

Before you start: Serena in Claude Desktop

  • uv
  • An LLM client supporting MCP
  • Additional language-specific dependencies where required

This command installs Serena; it is not the client launch command. Next run serena init, then configure your MCP client using the linked client guide. The default backend uses language servers. A separately started HTTP server is also supported, but no endpoint is stated in this README.

Serena Claude Desktop configuration

  1. Choose Claude Desktop configuration scope

    For Serena, open macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json. Merge under mcpServers via Settings → Developer → Edit Config when available.

  2. Add Serena to Claude Desktop

    Use the serena entry below in mcpServers. Keep Serena's documented stdio connection fields and your other Claude Desktop entries.

  3. Check Serena in Claude Desktop

    Serena: Fully quit and reopen Claude Desktop; check developer diagnostics.

Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

JSON
{
  "mcpServers": {
    "serena": {
      "command": "uv",
      "args": [
        "tool",
        "install",
        "-p",
        "3.13",
        "serena-agent"
      ],
      "env": {}
    }
  }
}

Serena tools available to Claude Desktop

Serena's stored tool list documents 6 tools; compare it with Claude Desktop's connected tool list, because the stored list is not a live check.

search_for_pattern

When Claude Desktop requests search_for_pattern from Serena, review the action before approving it.

Search a codebase using regular expressions.

replace_content

When Claude Desktop requests replace_content from Serena, review the action before approving it.

Apply literal or regex-based text substitutions.

list_dir

When Claude Desktop requests list_dir from Serena, review the action before approving it.

Inspect directory entries.

find_file

When Claude Desktop requests find_file from Serena, review the action before approving it.

read_file

When Claude Desktop requests read_file from Serena, review the action before approving it.

execute_shell_command

When Claude Desktop requests execute_shell_command from Serena, review the action before approving it.

Serena: full stored tool descriptions

Troubleshooting Serena in Claude Desktop

  • Serena's uv tool install command installs a package, not a persistent MCP process. Confirm the upstream launch command before connecting Claude Desktop.
  • Fully quit and reopen Claude Desktop for Serena. If uv is missing, check the desktop process's PATH, which may differ from your terminal.
  • Known limitation: Semantic capabilities depend on the selected backend and language server.
  • Known limitation: Interactive debugging and several advanced refactorings require the paid JetBrains plugin.
  • Known limitation: Some languages need additional dependencies.
  • General Claude Desktop troubleshooting lives in the /clients/claude-desktop guide.

Serena — details. Claude Desktop guide

Frequently asked questions

Claude Desktop loads Serena from claude_desktop_config.json: ~/Library/Application Support/Claude/ on macOS, or %APPDATA%\Claude\ on Windows. Open it via Settings → Developer → Edit Config when available.

Claude Desktop's serena example uses stdio.

Serena's Claude Desktop configuration invokes uv. Serena's uv tool install command installs a package, not a persistent MCP process. Confirm the upstream launch command before connecting Claude Desktop.

Serena's stored list contains 6 tools, including search_for_pattern, replace_content, list_dir. Compare those names with Claude Desktop's connected tool list; the stored list is not a live check.

No. It provides tools that an existing LLM or AI client orchestrates.

The default language-server backend is the free and open-source option. The JetBrains plugin is paid, with a trial available.