Serena MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Recuperação semântica apoiada por servidor de linguagem - localização de símbolos, referências, hierarquia de tipos
Edição simbólica – substituir corpo, excluir com segurança, inserir símbolo antes/depois
Mais de 40 linguagens via LSP (Python, TS/JS, Rust, Go, Java, C#, Ruby,…)
Refatoradores de arquivos cruzados – renomear, mover arquivo/diretório, inline, remoção de código morto
Memória persistente entre sessões de agente (por projeto)
Gratuito e local – sem API hospedada, sem taxa por token

Demo ao vivo

Como fica na prática

serena.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "serena",
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "serena": {
      "command": {
        "path": "uvx",
        "args": [
          "--from",
          "serena-agent",
          "serena",
          "start-mcp-server",
          "--context=claude-desktop"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add serena -- uvx --from serena-agent serena start-mcp-server --context=claude-desktop

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Serena

Encontre cada chamador de uma função em uma base de código de 1 milhão de linhas

👤 Engenheiros trabalhando em grandes repositórios maduros ⏱ ~10 min intermediate

Quando usar: Você precisa de uma lista completa e correta de chamadores - grep fornece falsos positivos (comentários, strings, funções com nomes semelhantes em outros escopos) e perde sobrecargas.

Pré-requisitos

instalado — curl -LsSf https://astral.sh/uv/install.sh | eh
Projeto aberto em um idioma que o LSP de Serena suporta — A maioria das linguagens convencionais funciona imediatamente

Fluxo

Abra o projeto

Abra /abs/path/to/repo com Serena. Confirme o índice LSP criado.✓ Copiado

→ Serena informa a raiz do projeto e o LSP que carregou
Encontre referências de símbolos

Encontre todos os sites de chamada de PaymentService.chargeCustomer. Inclui sobrecargas e substituições, exclui testes.✓ Copiado

→ Arquivo exato: lista de linhas, sem falsos positivos de comentários/strings
Resuma o impacto

Agrupe os locais de chamada por módulo. Para cada grupo, diga-me o que o chamador faz com o valor de retorno.✓ Copiado

→ Narrativa agrupada em módulos, não uma lista simples

Resultado: Você sabe exatamente o que uma mudança afetaria – antes de tocá-la.

Armadilhas

Alguns repositórios poliglotas precisam de vários LSPs — Inicie o Serena por subprojeto se os idiomas não compartilharem um servidor

Combine com: filesystem · github

Renomeie um símbolo de API pública sem quebrar dependentes

👤 Mantenedores de biblioteca/estrutura ⏱ ~15 min intermediate

Quando usar: Você está renomeando uma função ou classe que pode ser usada fora do arquivo - você precisa de uma renomeação precisa do LSP, não de uma substituição de texto.

Pré-requisitos

Limpe a árvore git — git status clean para que você possa revisar a diferença antes de confirmar

Fluxo

Execute a renomeação

Renomeie getUser para fetchUserById em src/api/users.ts. Use a renomeação simbólica de Serena. Visualize a diferença – não aplique ainda.✓ Copiado

→ Pré-visualização diferente em todos os arquivos afetados
Revise e inscreva-se

Aplique a renomeação. Diga-me qualquer arquivo que Serena sinalizou como ambíguo.✓ Copiado

→ Renomeação aplicada, lista de ambigüidades (se houver)
Execute o pacote

Execute os testes e relate as falhas, concentrando-se em qualquer coisa que faça referência ao nome antigo.✓ Copiado

→ Testes verdes ou uma lista precisa de falhas

Resultado: A renomeação é limpa em todo o repositório, incluindo reexportações públicas, barris index.ts e referências JSDoc obsoletas.

Armadilhas

O acesso dinâmico (obj['getUser']) não é capturado pela renomeação do LSP — Após a renomeação simbólica, execute um grep para a string de nome antigo; Serena revela qualquer coisa que não conseguiu resolver estaticamente

Combine com: filesystem · git

Substitua um corpo de função sem perturbar o código circundante

👤 Engenheiros fazendo edições cirúrgicas em arquivos grandes ⏱ ~10 min intermediate

Quando usar: Você deseja que a implementação de calculatePrice seja reescrita, mas sua assinatura e JSDoc sejam mantidos exatamente. A regeneração de arquivo inteiro é a ferramenta errada.

Fluxo

Direcione o símbolo

Em src/billing/pricing.ts, encontre calculatePrice. Mostre-me apenas o corpo atual (não a assinatura ou documento).✓ Copiado

→ Snippet apenas do corpo
Substitua o corpo

Substitua apenas o corpo por uma versão que lide com o caso de isenção de impostos. Mantenha a assinatura e o JSDoc intactos.✓ Copiado

→ A ferramenta de substituição de corpo de Serena é usada; assinatura inalterada no diff

Resultado: Diferença mínima e revisável - sem alteração acidental de espaços em branco/formatação.

Armadilhas

O agente volta para gravação de arquivo completo — Instrua explicitamente 'use a substituição simbólica de Serena, não write_file'

Combine com: filesystem

Integre-se a uma base de código desconhecida em uma hora

👤 Novas contratações, prestadores de serviços ou colaboradores de OSS ⏱ ~60 min beginner

Quando usar: Você acabou de clonar um repositório de 500 arquivos e precisa de um mapa mental antes de poder contribuir.

Fluxo

Obtenha a arquitetura

Abra este repositório com Serena. Construa um mapa: módulos de nível superior, suas exportações públicas e o principal ponto de entrada. Salve na memória da Serena como 'arch_overview'.✓ Copiado

→ Visão geral estruturada; nota de memória criada
Seguir uma solicitação do usuário

Rastreie o que acontece quando um usuário acessa POST/orders. Acompanhe-me em cada arquivo em ordem.✓ Copiado

→ Solicitação → manipulador → serviço → trilha de repositório, com pesquisas de referência de Serena
Observe as pegadinhas

Salve quaisquer padrões que pareçam incomuns (decoradores personalizados, constantes mágicas) na memória como 'pegadinhas'.✓ Copiado

→ Nota de memória salva para a próxima sessão

Resultado: Na próxima sessão, Claude já conhece o mapa – sem custo de reintegração.

Combine com: filesystem · github

Combinações

Combine com outros MCPs para 10× de alavancagem

serena + filesystem

Serena para navegação com reconhecimento de símbolos + sistema de arquivos para E/S arbitrária

Use Serena para encontrar o módulo de autenticação e, em seguida, o sistema de arquivos para escrever um novo README para essa pasta.✓ Copiado

serena + github

Refatore localmente com Serena; envie um branch e abra um PR via GitHub MCP

Renomeie ApiClient → HttpClient com Serena e abra um PR intitulado 'refactor (api): rename ApiClient'.✓ Copiado

serena + git

Revise o diff que Serena produziu antes de confirmar

Mostre-me git diff após a renomeação de Serena. Qualquer coisa suspeita, sinalize antes de nos comprometermos.✓ Copiado

serena + context7

Refatorador com reconhecimento de biblioteca – Serena para movimentos locais, Context7 para correspondência de APIs v-next

Migre este arquivo para os padrões Next.js 15. Use Context7 para as novas APIs e Serena para aplicar as alterações simbolicamente.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
find_symbol	name: str, scope?: str	Localize uma classe/função/var por nome com precisão LSP	free (local)
find_references	symbol: ref	Todos os chamadores/usos de um símbolo; muito melhor que grep	free
get_symbols_overview	path: str	Esboço do arquivo/módulo antes de decidir o que ler	free
rename_symbol	symbol: ref, new_name: str, dryRun?: bool	Renomeação segura em todo o projeto	free
replace_symbol_body	symbol: ref, new_body: str	Troque o corpo de uma função/método sem tocar na assinatura	free
insert_before_symbol / insert_after_symbol	symbol: ref, code: str	Adicione decoradores, importações ou declarações irmãs ancoradas em um nó AST	free
move_file / move_dir	src: str, dst: str	Realoque o código e deixe o LSP consertar cada importador	free
write_memory / read_memory	key: str, value?: str	Persistir o contexto do projeto (mapa de arquitetura, pegadinhas) entre as sessões	free
search_pattern	regex: str, path: str	Fallback quando o destino não é um símbolo nomeado (literais de string, padrões)	free

Custo e limites

O que custa rodar

Cota de API: Nenhum – LSP local
Tokens por chamada: Pequeno – Serena retorna trechos com escopo de símbolo, não arquivos inteiros
Monetário: Livre
Dica: Prefira get_symbols_overview + find_symbol a read_text_file em arquivos grandes – você gasta 10x menos tokens e obtém melhor sinal

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Nenhum – tudo funciona localmente

Saída de dados: Nenhum por padrão. Serena pode executar comandos shell (desativar); revise a lista de ferramentas antes de conceder acesso de gravação no Claude.

Nunca conceda: Access to directories outside your project

Serena pode executar comandos shell se você ativar a ferramenta relevante. Combine isso com raízes de projeto com escopo definido, nunca com uma raiz de diretório inicial.
As notas de memória são gravadas no disco no âmbito do projeto. Não guarde segredos na memória de Serena – é texto simples.

Solução de problemas

Erros comuns e correções

LSP falhou ao iniciar/nenhum símbolo encontrado

Verifique se o servidor de idioma está instalado para o idioma do projeto (por exemplo, pyright para Python, servidor de linguagem typescript para TS). Os logs de Serena listam qual LSP está usando.

Verificar: Run Serena in verbose mode; confirm LSP handshake succeeded

Renomear alguns arquivos ignorados

Geralmente significa que os arquivos não estão no espaço de trabalho do LSP. Confirme se a raiz do projeto é a raiz monorepo, não um subpacote.

Verificar: Ask Serena to list its workspace roots

O agente recorre à gravação de arquivos brutos em vez das ferramentas Serena

Coloque uma regra explícita em CLAUDE.md: 'Para operações simbólicas, use sempre as ferramentas da Serena; nunca escreva_file em arquivos .py/.ts existentes'

Verificar: Re-run the task; inspect tool_use calls in the trace

uvx: comando não encontrado

Instale o uv primeiro: curl -LsSf https://astral.sh/uv/install.sh | sh; então reabra seu terminal

Verificar: uvx --version

Alternativas

Serena vs. outros

Alternativa	Quando usar	Troca
JetBrains MCP	Você já mora em um IDE JetBrains e deseja que o agente conduza suas ferramentas de refatoração	Requer um processo IDE aberto; mais pesado
filesystem	Você não precisa de reconhecimento de símbolos - apenas leia/grave arquivos	Nenhuma pesquisa semântica ou renomeação segura
mcp-language-server	Você quer um wrapper menor somente LSP, não a memória + camada shell de Serena	Menos ferramentas de alto nível; você mesmo compõe o fluxo de trabalho

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills