Skip to content

Claude Code Complete Guide

Serena MCP Setup Guide: Claude Code, Codex & JetBrains (2026)

Updated February 2026

  • v1.0.0 approaching (v0.1.4 was last pre-release)
  • Codex CLI officially supported with --context codex
  • JetBrains Plugin released
  • 30+ languages now supported
  • Breaking: replace_regex tool removed from ide-assistant/codex contexts

Introduction

Boost your Claude workflow with AI task automation. Serena MCP server transforms Claude Desktop and Claude Code into powerful development assistants with semantic code analysis and intelligent task completion. This guide shows the correct setup using Python uv (not npm) for reliable AI-powered development assistance in just 5 minutes. Perfect for developers wanting to accelerate coding productivity with automated file analysis, debugging support, and intelligent code suggestions.

Key Points

  • Complete setup: enable Claude + Serena integration fast
  • Real project use: improve first-time response with indexing
  • Secure operation: control read_only and shell command tools

Serena MCP server quick checklist (Nov 2025)

3 steps before deep diving

  1. Confirm the Serena MCP server starts via uv — run uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$(pwd)" and open http://localhost:24282/dashboard/index.html.
  2. Align every client profile — use claude mcp add for Claude Code, edit %APPDATA%/Claude/claude_desktop_config.json (or the macOS path) for Claude Desktop, and register Serena in .cursor/mcp.json or the Cursor settings UI.
  3. Lock down YAML configs first — keep read_only: true inside ~/.serena/serena_config.yml and <project>/.serena/project.yml, then enable extra tools only when you understand the risk.

Including the phrase “Serena MCP server” directly in the heading and checklist helps match common search intents while giving newcomers a one-screen path to success.

1. Quickstart (verify connectivity first)

# Run at project root
claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

1.2 Optional: speed up first run with indexing

uvx --from git+https://github.com/oraios/serena serena project index

1.3 Sanity checks

  • Dashboard: http://localhost:24282/dashboard/index.html
  • Confirm Claude can retrieve /mcp__serena__initial_instructions (manual view on older versions)

2. Client-specific Setup

claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

Run uvx ... serena project index as needed to speed up first responses.

2.2 Claude Desktop (edit local JSON)

Edit claude_desktop_config.json (OS-specific paths):

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "desktop-app"]
    }
  }
}

Fully restart the app after saving. Logs appear in the same directory as mcp.log or mcp-server-*.log. Check the MCP icon (hammer) for connection status.

2.3 Cursor (per project)

Create or edit .cursor/mcp.json:

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

Note: On Windows, project-level mcp.json may not apply due to known issues. In that case, register via Cursor's settings UI for more reliable results.

2.4 Codex CLI (OpenAI)

New in 2026

Serena MCP now officially supports Codex CLI with the --context codex option.

Edit ~/.codex/config.toml:

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

Note: Codex may show "failed" status for MCP servers, but tools still work correctly (known Codex bug).

2.5 JetBrains IDEs (Junie / AI Assistant)

New in 2026

JetBrains Plugin released — leverages powerful IDE code analysis capabilities.

Configure MCP in JetBrains IDE settings. The --context ide is recommended for JetBrains integration.

3. Config Files (YAML is correct)

Serena generates YAML configs on first run.

# ~/.serena/serena_config.yml (user settings)
record_tool_usage_stats: true
included_optional_tools: []

# <project>/.serena/project.yml (project settings)
read_only: true    # start with true, then enable needed tools incrementally
project_name: my_project

Safety note: execute_shell_command is powerful but risky. Start with read_only: true and incrementally enable write-capable tools only after understanding their scope.

4. Dashboard and SSE

  • Dashboard: http://localhost:24282/dashboard/index.html (enabled by default)
  • SSE connection (use only when needed):
uv run serena start-mcp-server --transport sse --port 9121

Note: Docker is experimental and may behave differently regarding ports and GUI. Direct uv invocation is recommended for production use.

5. Common Pitfalls and Correct Snippets

  • Wrong: npm install @oraios/serena / node ./node_modules/@oraios/serena/dist/index.js Correct: uvx --from git+https://github.com/oraios/serena serena start-mcp-server

  • Wrong: generic mcp-config.json anywhere Correct: client-specific locations (Claude Desktop: claude_desktop_config.json, Cursor: .cursor/mcp.json, Claude Code: claude mcp add ...)

  • Wrong: .serenarc.json (JSON) Correct: ~/.serena/serena_config.yml and <project>/.serena/project.yml (YAML, auto-generated)

6. Troubleshooting (known topics)

Claude Desktop not recognizing server

  1. Fully restart the app (quit from system tray)
  2. Check JSON syntax (commas, brackets)
  3. Use absolute paths (Windows %APPDATA% expansion issues can be worked around with env explicit variables)
  4. Test manual start: uvx --from git+https://github.com/oraios/serena serena start-mcp-server
  5. Check logs: mcp.log / mcp-server-*.log for error details
  6. MCP Inspector (official debug tool) for server connectivity tests

Cursor mcp.json not working (Windows)

On Windows, project-level .cursor/mcp.json may not apply due to known bugs. Register via Cursor Settings UI (Settings > Features > Model Context Protocol) for more reliable results.

Serena tools showing "failed"

Some clients (like Codex) have display bugs where tools appear to fail but actually succeed. Check the dashboard or logs for actual execution results.

General debug steps

  • Start with read_only: true and disable risky tools to isolate causes
  • Check Serena GitHub Issues for known stability/connectivity items

7. CI/Operations (pragmatic boundaries)

  • MCP follows a client-starts-server model. Using Serena as a direct Node library in CI is not recommended (keep static analysis in ESLint/flake8/mypy)
  • Use Serena for interactive assistance and local workflow acceleration. Keep CI/CD static analysis with existing tools
  • Free/no API key needed: Serena itself is a free toolkit, but LLM usage terms depend on your client (check Claude etc. license terms)
  • Start with read_only: true and enable only minimal necessary tools incrementally

Summary

  • Use uv-based MCP server as the canonical approach; avoid npm/Node assumptions
  • Config is YAML (~/.serena/serena_config.yml, <project>/.serena/project.yml) and auto-generated
  • Config locations are client-specific:
  • Claude Code: claude mcp add (CLI recommended)
  • Claude Desktop: claude_desktop_config.json (OS-specific paths)
  • Cursor: .cursor/mcp.json (Windows issues—use UI for reliability)
  • Safety first: read_only: true → dashboard check → indexing → incremental tool enablement
  • Debug tools: logs (mcp.log etc.), MCP Inspector, GitHub Issues

References

  1. Published on 2025-08-15, Serena v0.1.4 backports Codex CLI compatibility fixes, expands the CLI, and adds Swift/Bash language servers so users installing from tags avoid the MCP dependency breakage. ↩