Using Serena

Serena is an MCP server that enhances AI agents with IDE-like tools for semantic code analysis and manipulation. It supports 30+ programming languages through Language Server Protocol (LSP) integration, enabling agents to find symbols, navigate code relationships, and edit at the symbol level — ideal for navigating and editing large, well-structured codebases.

Quick Start

Recommended: Import shared workflow

The preferred way to add Serena is to copy the file shared/mcp/serena.md into your repo and import it into your workflow, which configures the complete MCP server automatically:

---
on: issues

engine: copilot

permissions:
  contents: read
# NOTE: first copy `shared/mcp/serena.md` into your repository before importing it

imports:
  - uses: shared/mcp/serena.md
    with:
      languages: ["go", "typescript"]
---

For Go-only workflows, use the convenience wrapper (copy shared/mcp/serena-go.md into your repository before importing it):

---
on: issues

engine: copilot

permissions:
  contents: read
# NOTE: first copy `shared/mcp/serena-go.md` into your repository before importing it

imports:
  - shared/mcp/serena-go.md
---

Example: Code Analysis

---
engine: copilot

permissions:
  contents: read

imports:
  - uses: shared/mcp/serena.md
    with:
      languages: ["go"]

tools:
  github:
    toolsets: [default]
---

# Code Quality Analyzer

Analyze Go code for quality improvements:
1. Find all exported functions and check for missing documentation
2. Identify code patterns and suggest improvements

Language Support

Serena supports 30+ programming languages through Language Server Protocol (LSP):

Category	Languages
Systems	C, C++, Rust, Go, Zig
JVM	Java, Kotlin, Scala, Groovy (partial)
Web	JavaScript, TypeScript, Dart, Elm
Dynamic	Python, Ruby, PHP, Perl, Lua
Functional	Haskell, Elixir, Erlang, Clojure, OCaml
Scientific	R, Julia, MATLAB, Fortran
Shell	Bash, PowerShell
Other	C#, Swift, Nix, Markdown, YAML, TOML

[!NOTE] Some language servers require additional dependencies. Most are automatically installed by Serena, but check the Language Support documentation for specific requirements.

Available Tools

Serena provides semantic code tools organized into three categories:

Category	Tools
Symbol Navigation	find_symbol, find_referencing_symbols, get_symbol_definition, list_symbols_in_file
Code Editing	replace_symbol_body, insert_after_symbol, insert_before_symbol, delete_symbol
Project Analysis	find_files, get_project_structure, analyze_imports

These tools enable agents to work at the symbol level rather than the file level, making code operations more precise and context-aware.

Usage Examples

Find Unused Functions

---
engine: copilot

imports:
  - shared/mcp/serena-go.md

tools:
  github:
    toolsets: [default]
---

# Find Unused Code

1. Configure memory: `mkdir -p /tmp/gh-aw/cache-memory/serena`
2. Use `find_symbol` and `find_referencing_symbols` to identify unused exports
3. Report findings

Best Practices

Pre-create the cache directory (mkdir -p /tmp/gh-aw/cache-memory/serena) for faster operations — Serena reuses language server indexes across runs. Pin the key with tools.cache-memory.key: serena-analysis in frontmatter to persist it. Prefer symbol-level operations (replace_symbol_body) over file-level edits. Combine Serena with other tools like github, edit, and bash for complete workflows. For large codebases, start with targeted analysis of specific packages before expanding scope.

Troubleshooting

Language server not found: Install required dependencies (e.g., go install golang.org/x/tools/gopls@latest for Go).

Memory permission issues: Ensure cache directory exists with proper permissions: mkdir -p /tmp/gh-aw/cache-memory/serena && chmod 755 /tmp/gh-aw/cache-memory/serena

Slow initial analysis: Expected behavior as language servers build indexes. Subsequent runs use cached data.

Related Documentation

• Imports Reference - Full imports and import-schema syntax
• Using MCPs - General MCP server configuration
• Tools Reference - Complete tools configuration
• Using MCPs - MCP introduction
• Serena GitHub Repository — official repo and documentation
• Language Support - Supported languages and dependencies
• Serena Tools Reference - Complete tool documentation