How to Set Up Serena for Your AI Coding Agent — Practical Tutorial

Setting Up Serena for Your AI Coding Agent — A Step-by-Step Tutorial

Estimated time: 10 minutes. Grab a coffee — this is worth it.

I remember the first time I tried to get an AI agent to help with a complex refactor in a 50,000-file monorepo. The agent kept getting lost. It would find a reference here, miss one there, and leave my codebase in a state that made me want to revert everything and give up on AI coding altogether.

The problem wasn't the agent. The problem was that the agent was blind — it had no IDE-level understanding of the code it was editing. It was working with text files and grep, while a human developer would have VS Code with language server, symbol navigation, and refactoring tools.

Serena fixes this. Here's exactly how to set it up.

Prerequisites

Before starting, make sure you have:

• Node.js 18+ installed — Serena runs as a Node.js MCP server
• An MCP-compatible client — Claude Code, Codex CLI, Cursor, or any IDE with MCP support
• Your project — ideally a real codebase with more than just a few files (you want to see Serena shine)

Step 1: Install Serena

There are two ways to install Serena. The recommended way is via npm. Let's start with that:

# Install globally
npm install -g @oraios/serena

# Or add to your project
npm install --save-dev @oraios/serena

Why I recommend the global install: If you're working across multiple projects (and let's be honest, who isn't these days?), the global install lets you add Serena to any MCP client without project-specific setup. It also keeps Serena out of your node_modules — which matters if you're working in a non-Node.js project and just want the MCP tools.

If you prefer Docker (more on that later), you can also pull the image:

docker pull idoogroup/serena:latest

Step 2: Connect Serena to Your AI Client

This is where it gets specific. The setup depends on which MCP client you're using. Here are the most common ones:

Claude Code (Terminal)

Add this to your ~/.claude/claude_desktop_config.json or equivalent MCP config:

{
  "mcpServers": {
    "serena": {
      "command": "npx",
      "args": ["-y", "@oraios/serena"],
      "env": {
        "SERENA_PORT": "8080"
      }
    }
  }
}

⚠️ What tripped me up: I originally put the port as a regular arg instead of in env. Took me 10 minutes to realize Serena reads it from environment variables. Don't make my mistake.

Codex CLI

Edit your ~/.codex/config.json:

{
  "mcpServers": {
    "serena": {
      "command": "npx",
      "args": ["-y", "@oraios/serena"]
    }
  }
}

Cursor / VS Code with Continue

If you're using Cursor's built-in MCP support or the Continue extension in VS Code, same pattern — just add the MCP server to your config and restart.

Step 3: Verify It's Working

After restarting your AI client, try giving your agent a simple command:

"Use Serena to find all references to the UserService class"

If your agent responds with actual references — file paths, line numbers, symbol names — it's working. If it says "I don't have access to Serena tools," check your MCP config paths and restart.

Quick test: Ask your agent "What tools do you have available?" You should see Serena's tools in the list — things like findSymbol, findReferences, renameSymbol, etc.

Step 4: Try Your First Real Task

Here's the task I always recommend as a first test:

"Using Serena, find every usage of the DeprecatedApiClient class and tell me:
- How many files reference it?
- What are the top 3 most common calling patterns?
- Which file has the most usages?"

This is a task that pure grep would fail at — it would return string matches in comments, generated code, and test fixtures. Serena's symbol-level understanding filters all that noise automatically.

Step 5: Use Docker for Consistent Environments

If you're working in a team or deploying Serena alongside a CI pipeline, Docker is your friend. Here's a minimal setup:

docker run -d \
  --name serena \
  -p 8080:8080 \
  -v $(pwd):/workspace \
  idoogroup/serena:latest

Then configure your MCP client to connect to http://localhost:8080. This is especially useful if you want your entire team using the same Serena version.

Common Problems and How I Fixed Them

What's Next?

Once you have Serena running, I recommend exploring its full tool set. The findImplementations tool is fantastic for tracing interface implementations across your codebase. The getSymbolInfo tool gives you hover-level documentation. And the cross-file rename is a lifesaver during refactoring sprints.

The Serena docs at oraios.github.io/serena have a full tool reference — but honestly, the best way to learn is to just start asking your agent to do things and see what it can do. My personal tip: start with "Find all symbols related to X" and go from there.

Happy coding — your agent's IDE glasses are on.