How to Set Up Serena MCP Server (2026)

How to Set Up Serena MCP Server in 2026

Serena is a Model Context Protocol (MCP) server that gives AI coding assistants deep, semantic understanding of your codebase. Instead of just reading files as plain text, Serena uses Language Server Protocol (LSP) analysis to provide your AI with information about symbols, types, references, and call hierarchies -- the same intelligence that powers your IDE's "Go to Definition" and "Find References" features.

This guide walks you through installing, configuring, and using Serena with popular AI coding tools like Claude Code and Cursor.

What Makes Serena Different?

Most MCP servers for code provide basic file read/write access. Serena goes further by integrating with language servers to provide:

• Symbol lookup: Find where functions, classes, and variables are defined
• Reference search: Find all usages of a symbol across the codebase
• Type information: Understand types, interfaces, and signatures
• Call hierarchy: See what calls a function and what it calls
• Diagnostics: Get compiler errors and warnings
• Smart rename: Rename symbols across the entire project safely

This means your AI assistant can answer questions like "where is this function used?" or "what type does this return?" without scanning every file.

Prerequisites

Before setting up Serena, ensure you have:

1. Node.js 18+ installed
2. An MCP-compatible AI tool: Claude Code, Cursor, Windsurf, or Cline
3. A language server for your project's language (Serena supports TypeScript, Python, Go, Rust, Java, and more)
4. Git (Serena works best with Git repositories)

Step 1: Install Serena

Install Serena globally via npm:

npm install -g serena-mcp

Or use it directly with npx (no install required):

npx serena-mcp

Verify the installation:

serena-mcp --version

Step 2: Configure for Your Language

Serena needs to know which language server to use for your project. Create a serena.config.json in your project root:

For TypeScript/JavaScript projects:

{
  "language": "typescript",
  "rootPath": ".",
  "tsconfig": "./tsconfig.json",
  "exclude": ["node_modules", "dist", ".next"]
}

For Python projects:

{
  "language": "python",
  "rootPath": ".",
  "pythonPath": "/usr/bin/python3",
  "exclude": ["venv", "__pycache__", ".mypy_cache"]
}

For Go projects:

{
  "language": "go",
  "rootPath": ".",
  "gopath": "$GOPATH",
  "exclude": ["vendor"]
}

For Rust projects:

{
  "language": "rust",
  "rootPath": ".",
  "exclude": ["target"]
}

Step 3: Connect to Claude Code

Add Serena to your Claude Code MCP configuration at ~/.claude/mcp_servers.json:

{
  "serena": {
    "command": "npx",
    "args": ["serena-mcp", "--project", "/path/to/your/project"],
    "env": {}
  }
}

Restart Claude Code and verify the connection:

/mcp

You should see Serena listed with its available tools.

Step 4: Connect to Cursor

Add Serena to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "serena": {
      "command": "npx",
      "args": ["serena-mcp", "--project", "."],
      "env": {}
    }
  }
}

Step 5: Connect to Cline (VS Code)

In your Cline MCP settings (VS Code settings), add:

{
  "serena": {
    "command": "npx",
    "args": ["serena-mcp", "--project", "${workspaceFolder}"],
    "env": {}
  }
}

Available MCP Tools

Once connected, Serena exposes the following tools to your AI assistant:

Tool	Description	Example Prompt
find_symbol	Find a symbol definition by name	"Where is the UserService class defined?"
find_references	Find all references to a symbol	"Where is calculateTotal used?"
get_type_info	Get type information for a symbol	"What type does fetchUser return?"
get_diagnostics	Get compiler errors and warnings	"Are there any type errors in this file?"
get_call_hierarchy	Show incoming and outgoing calls	"What functions call validateInput?"
rename_symbol	Rename a symbol across the project	"Rename oldName to newName everywhere"
get_document_symbols	List all symbols in a file	"What functions are in auth.ts?"
get_workspace_symbols	Search symbols across the workspace	"Find all classes with 'Controller' in the name"
get_hover_info	Get hover documentation for a symbol	"What does parseJSON do?"
get_completions	Get code completions at a position	Used internally by the AI

Practical Usage Examples

Understanding a New Codebase

When you join a new project, ask your AI assistant:

Using Serena, give me an overview of the main classes and their
relationships in the src/services/ directory.

The AI will use get_document_symbols and get_call_hierarchy to map out the architecture.

Safe Refactoring

Instead of find-and-replace, use Serena's semantic rename:

Rename the `getUserById` function to `findUserById` across the entire
codebase, making sure all references are updated.

Serena's rename_symbol tool updates all usages, imports, and references -- not just string matches.

Debugging Type Errors

When you have a TypeScript error you cannot figure out:

Use Serena to check the diagnostics for src/api/routes.ts and explain
the type errors.

The AI will pull actual compiler diagnostics rather than guessing from the code text.

Tracing Data Flow

To understand how data flows through your application:

Using Serena, trace the call hierarchy of the `processPayment` function.
Show me everything that calls it and everything it calls.

Configuration Options

Serena supports additional configuration in serena.config.json:

{
  "language": "typescript",
  "rootPath": ".",
  "tsconfig": "./tsconfig.json",
  "exclude": ["node_modules", "dist"],
  "maxFileSize": 1048576,
  "indexOnStartup": true,
  "watchFiles": true,
  "diagnostics": {
    "enable": true,
    "severity": ["error", "warning"]
  },
  "completions": {
    "enable": true,
    "maxResults": 50
  }
}

Option	Default	Description
language	auto-detect	Language server to use
rootPath	.	Project root directory
exclude	["node_modules"]	Directories to exclude from indexing
maxFileSize	1MB	Maximum file size to index
indexOnStartup	true	Index the project when the server starts
watchFiles	true	Watch for file changes and re-index

Supported Languages

Language	Language Server	Setup
TypeScript/JavaScript	typescript-language-server	Auto-installed
Python	pylsp or pyright	pip install python-lsp-server
Go	gopls	go install golang.org/x/tools/gopls@latest
Rust	rust-analyzer	Install via rustup
Java	Eclipse JDT	Auto-downloaded
C/C++	clangd	Install via package manager
Ruby	solargraph	gem install solargraph

Troubleshooting

Serena fails to start: Check that the required language server is installed. For Python, run pip install python-lsp-server. For Go, ensure gopls is on your PATH.

# Verify language server is available
which typescript-language-server  # TypeScript
which pylsp                       # Python
which gopls                       # Go
which rust-analyzer               # Rust

Slow indexing on large projects: Add more directories to the exclude list. For monorepos, point Serena at a specific package rather than the root.

Stale results after code changes: If watchFiles is enabled, Serena should auto-update. If not, restart the MCP server. In Claude Code, use /mcp to restart.

Symbol not found errors: Ensure your project has a valid configuration file (e.g., tsconfig.json for TypeScript, pyproject.toml for Python). The language server needs these to understand your project structure.

High memory usage: Large projects with many files can consume significant memory. Use the maxFileSize option to skip large generated files, and exclude build output directories.

Serena vs. Basic File-Based MCP

Capability	Basic File MCP	Serena
Read files	Yes	Yes
Write files	Yes	Yes
Symbol lookup	No (text search only)	Yes (semantic)
Find references	No	Yes (all usages)
Type information	No	Yes
Call hierarchy	No	Yes
Rename refactoring	No	Yes (safe rename)
Diagnostics	No	Yes (compiler errors)
Code intelligence	No	Yes

Conclusion

Serena transforms your AI coding assistant from a text-based tool into a code-aware partner. By providing semantic understanding of your codebase through the Language Server Protocol, it enables more accurate refactoring, better bug diagnosis, and deeper architectural understanding.

If you are building AI-powered products and need reliable media generation APIs, Hypereal AI offers image generation, video creation, lip sync, voice cloning, and more through a single unified API. With pay-as-you-go pricing and access to the latest models, Hypereal is the fastest way to add AI media capabilities to your application.