Serena MCP: AI che Comprende Davvero il Tuo Codice

Lavoro con Claude Code ogni giorno. Lo uso per scrivere codice, refactorare, analizzare architetture. Ma c'e un limite che ho sentito spesso: Claude legge i file come testo. Non "capisce" la struttura del codice: non sa che quella funzione e un metodo di una classe, non conosce le dipendenze tra simboli, non naviga il progetto come farebbe un IDE.

Serena risolve esattamente questo problema.

Cos'e Serena

Serena e un server MCP open-source che fornisce a Claude (e a qualsiasi altro LLM compatibile) gli stessi strumenti di un IDE: navigazione semantica, ricerca di simboli, analisi delle dipendenze e editing a livello di funzione.

In pratica, invece di leggere interi file per trovare una funzione, Claude puo chiedere a Serena: "dammi il corpo del metodo getArticleBySlug", e ricevere solo quello. Invece di fare grep per capire dove viene usata una classe, puo chiamare find_referencing_symbols e ottenere una mappa precisa.

La differenza e sostanziale. Si passa dal "leggo tutto e spero di trovare quello che serve" al "chiedo esattamente quello che mi serve". Meno token consumati, risposte piu precise, meno errori.

Quanto costa

Zero. Serena e completamente gratuito e open-source (licenza MIT). Non ci sono piani a pagamento, limiti di utilizzo o feature premium. Il progetto e mantenuto dalla community su GitHub e ha oltre 17.000 stelle.

L'unico costo e quello del modello LLM che usi, Claude, nel mio caso. Ma Serena di per se non aggiunge nessun costo.

Cosa offre in pratica

Serena espone una trentina di tool che Claude puo usare autonomamente. Si dividono in tre categorie principali.

Navigazione e comprensione

get_symbols_overview: panoramica dei simboli in un file (classi, funzioni, costanti)
find_symbol: cerca un simbolo per nome, con supporto per path gerarchici (MyClass/myMethod)
find_referencing_symbols: trova tutti i punti del codice che usano un simbolo specifico
search_for_pattern: ricerca regex flessibile nell'intero codebase

Editing semantico

replace_symbol_body: sostituisce il corpo di una funzione o classe intera
insert_after_symbol / insert_before_symbol: inserisce codice prima o dopo un simbolo
replace_content: sostituzione regex dentro un file specifico

Gestione progetto

list_dir / find_file: esplorazione del filesystem
read_file: lettura di file (o porzioni specifiche)
execute_shell_command: esecuzione comandi shell
write_memory / read_memory: sistema di memorie persistenti tra conversazioni

Il punto chiave e che Claude sceglie autonomamente quali tool usare. Basta dire "aggiungi un metodo getLatestArticles dopo getArticles in db.php" e Serena trova il simbolo, individua la posizione e inserisce il codice nel punto giusto.

Perche usarlo

Ho iniziato a usare Serena per un motivo preciso: risparmio di token e precisione.

Senza Serena, Claude legge file interi per trovare una funzione. Un file da 200 righe viene caricato tutto nel contesto, anche se servono solo 10 righe. Con Serena, Claude chiede solo il corpo del simbolo che gli interessa. In un progetto medio, questo si traduce in un consumo di token significativamente inferiore.

Ma il vantaggio piu importante e la comprensione strutturale. Serena usa il Language Server Protocol (LSP), lo stesso protocollo che alimenta l'autocompletamento e la navigazione in VS Code, PhpStorm e tutti gli IDE moderni. Questo significa che quando Claude chiede "chi chiama questa funzione?", la risposta non viene da un grep testuale ma da un'analisi semantica reale del codice.

Supporta oltre 30 linguaggi: PHP, Python, JavaScript/TypeScript, Java, Go, Rust, C/C++, Ruby, Swift, Kotlin e molti altri.

L'altro motivo e il sistema di memorie. Serena permette di salvare informazioni sul progetto che persistono tra le conversazioni. L'onboarding iniziale analizza il codebase e salva struttura, convenzioni e comandi utili. La prossima volta che apri una conversazione, Claude ha gia tutto il contesto, senza dovergli rispiegare il progetto.

Come configurarlo

Prerequisito: uv

Serena si installa tramite uv, il package manager Python di Astral. Se non lo hai:

curl -LsSf https://astral.sh/uv/install.sh | sh

Setup per Claude Code (consigliato)

Per un progetto specifico, dalla directory del progetto:

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

Il flag --context claude-code disabilita i tool che duplicherebbero quelli gia integrati in Claude Code (lettura file, editing base), lasciando solo quelli semantici.

Per una configurazione globale (che funziona su tutti i progetti):

claude mcp add --scope user serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server \
  --context=claude-code \
  --project-from-cwd

Con --project-from-cwd, Serena cerca automaticamente un file .serena/project.yml o un .git risalendo dalla directory corrente.

Setup per Claude Desktop

Apri File → Impostazioni → Sviluppatore → MCP Servers → Modifica Configurazione e aggiungi:

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

Dopo aver salvato, chiudi completamente Claude Desktop (File → Esci, non solo la X) e riaprilo. I tool Serena compariranno con l'icona del martello nella chat.

Configurazione del progetto

Quando attivi Serena su un progetto per la prima volta, viene creata una directory .serena/ con un file project.yml. Qui puoi configurare:

project_name: "mio-progetto"
languages:
  - php
  - typescript
encoding: "utf-8"
ignored_paths:
  - "vendor/**"
  - "node_modules/**"
  - "db/**"

I linguaggi determinano quali language server vengono avviati. I path ignorati velocizzano la scansione escludendo directory irrilevanti.

Il sistema di memorie

Una delle feature piu utili. Al primo utilizzo, Serena suggerisce di fare un onboarding: analizza il progetto e salva in file .md le informazioni chiave: struttura, convenzioni, comandi utili, checklist post-task.

Queste memorie vivono in .serena/memories/ e persistono tra conversazioni. La prossima volta che lavori sul progetto, Claude carica le memorie rilevanti e ha gia il contesto necessario.

Puoi anche scrivere memorie manualmente con write_memory, ad esempio per annotare decisioni architetturali o workaround specifici.

Un esempio reale

Nel mio portfolio (PHP vanilla + SQLite) ho configurato Serena cosi:

languages:
  - php
  - typescript
ignored_paths:
  - "vendor/**"
  - "articles/**"
  - "db/**"

L'onboarding ha generato quattro memorie: overview del progetto, code style, comandi suggeriti e checklist di completamento task. Ora quando chiedo a Claude "aggiungi una funzione per contare gli articoli per mese", lui:

Legge la memoria project_overview per capire la struttura
Usa find_symbol per trovare le funzioni esistenti in db.php
Analizza le convenzioni con la memoria code_style
Inserisce la funzione nel punto giusto con insert_after_symbol

Tutto senza che io debba spiegare nulla del progetto. Il contesto e gia li.

Cose da sapere

Non sostituisce Claude Code. Serena lo potenzia. I tool base di Claude Code (lettura file, editing, bash) restano attivi. Serena aggiunge lo strato semantico che manca.

Primo avvio lento. Il language server ha bisogno di indicizzare il progetto. Il primo find_symbol potrebbe essere lento; poi la cache velocizza tutto.

Funziona offline. Serena gira interamente in locale. Nessun dato del tuo codice esce dalla macchina (a parte quello che invii a Claude, ovviamente).

In sviluppo attivo. Il progetto e molto attivo su GitHub con oltre 2.000 commit. Nuove feature e linguaggi vengono aggiunti regolarmente.

Il repository e su GitHub: github.com/oraios/serena

Serena MCP - Come Dare al Tuo AI una Comprensione Reale del Codice