A Serena MCP dá ao Claude Code ferramentas em nível de símbolo, e com elas vem acesso real de escrita. Veja o que a ferramenta de shell pode fazer, quantos tokens custam as definições das ferramentas, os comandos exatos de configuração e uma implantação somente leitura que mantém seu repositório seguro.
A Serena MCP é segura para usar se você a tratar como qualquer ferramenta que pode editar seu código, porque é exatamente isso que ela é. O servidor roda na sua própria máquina, o código-fonte é público e, no contexto claude-code, a ferramenta de shell dela vem desligada. As perguntas reais são mais específicas: o que ela pode gravar no disco, o que ela envia para fora e quantos tokens ela consome antes de você digitar qualquer prompt? Este artigo responde às três com comandos exatos, nomes de configuração e uma ordem de implantação que você pode seguir hoje.
Uma observação rápida sobre as fontes. Os comandos e configurações abaixo vêm do repositório da Serena e da página de configuração de clientes. Os números de tokens vêm de um wrapper de terceiros e de um texto sobre segurança, e eu indico isso. Meça a sua própria configuração antes de confiar em qualquer número, inclusive nos meus.
A Serena, criada pela Oraios, é um servidor MCP que entrega ao agente de programação ferramentas no estilo de IDE. Em vez de ler arquivos inteiros e procurar textos, o agente pede símbolos: classes, funções, métodos e os lugares que os referenciam. O repositório lista ferramentas de recuperação (encontrar símbolo, visão geral do símbolo, encontrar símbolos que referenciam), edição simbólica (substituir o corpo de um símbolo, inserir antes ou depois de um símbolo), busca por regex, operações com arquivos, execução de shell e um sistema de memória persistente. O suporte a linguagens passa de 40 linguagens por meio de servidores de linguagem.
Quem ganha com isso? Qualquer pessoa que trabalhe em um repositório grande demais para caber em um único prompt: backends com vários módulos, monorepos, apps antigos em que renomear um símbolo toca trinta arquivos. Se o seu projeto são alguns scripts, as ferramentas simples do Claude Code já bastam, e adicionar um servidor aumenta sobretudo a superfície de exposição. Ajuste a ferramenta ao tamanho do problema antes de começar a perguntar se ela é segura.
Um agente comum encontra uma função buscando texto e depois lê os arquivos ao redor para ter certeza de que achou a certa. A Serena pergunta a um servidor de linguagem, então a resposta é a própria definição, não um monte de arquivos.
| Tarefa | Ferramentas comuns de arquivo | Ferramentas da Serena |
|---|---|---|
| Encontrar uma função | Buscar texto, ler arquivos inteiros | Encontrar símbolo retorna a definição |
| Ver quem a chama | Buscar e adivinhar | Encontrar símbolos que referenciam |
| Editar um método | Reescrever um bloco de texto | Substituir corpo do símbolo |
| Se orientar em um arquivo | Ler o arquivo completo | Visão geral do símbolo |
O Claude Code inicia a Serena como um processo local, e os servidores de linguagem também rodam localmente. A Serena não é um serviço hospedado e, pelo que a documentação pública mostra, não existe uma nuvem da Serena que receba seu repositório. Há um ponto importante que vale dizer em voz alta: tudo o que uma ferramenta da Serena retorna cai no contexto do Claude, e esse contexto vai para a API do modelo como qualquer outro resultado de ferramenta. A Serena não torna a sessão mais privada. Ela torna as leituras menores e mais precisas.
Para a maioria dos desenvolvedores que trabalham nos próprios repositórios, sim, com condições. Os riscos são comuns, e cada um tem um controle que você pode configurar em minutos.
Comece pelo modelo de ameaça. Você não está preocupado com um estranho invadindo a Serena. Está preocupado com três coisas mais discretas: o agente alterar arquivos que você não queria alterar, o agente executar um comando que você não queria executar e um texto dentro de um arquivo convencer o agente a fazer uma dessas coisas. Essa última é a injeção de prompt, e ela vale para qualquer ferramenta que leia conteúdo não confiável. Um repositório clonado, uma dependência baixada ou um issue colado podem conter uma frase endereçada ao modelo, e não a você. Uma lista curta de ferramentas e um pedido de permissão para gravações são a melhor defesa, porque limitam aonde uma instrução sequestrada consegue chegar.
| Área | Risco | Controle |
|---|---|---|
| Gravações de arquivo | Edições de símbolo alteram arquivos no disco | read_only: true, uma árvore git limpa, revisão de diff |
| Shell | execute_shell_command executa comandos arbitrários | Excluído no contexto claude-code, além de excluded_tools |
| Telemetria | Relatórios de uso anônimos | SERENA_USAGE_REPORTING=false |
| Cadeia de suprimentos | Executar direto de uma URL git | Instalar o pacote ou fixar uma tag |
| Injeção de prompt | Texto dentro de um repositório pode instruir o agente | Pedidos de permissão, lista pequena de ferramentas |
| Licença | Código da aplicação sob GPL-3.0-or-later | Leia antes de redistribuir |
O código da aplicação da Serena é GPL-3.0-or-later, e a camada SolidLSP incluída é MIT. Código aberto significa que você pode ler exatamente o que roda na sua máquina, o que é uma propriedade de segurança real. Rodar uma ferramenta GPL no seu próprio repositório não altera a licença do repositório. A licença passa a importar quando você modifica a Serena e a distribui para outras pessoas, e nesse ponto você deve perguntar a um advogado, não a um blog.
A ferramenta mais poderosa do conjunto é execute_shell_command. Um texto de segurança sobre a Serena a chama de capacidade mais perigosa, com exclusão acidental de arquivos, vazamento de credenciais e configurações de sistema quebradas como modos de falha, e sugere reservá-la para ambientes de CI em vez do trabalho local.
O contexto claude-code já a remove. Esse contexto exclui seis ferramentas: create_text_file, read_file, execute_shell_command, find_file, list_dir e search_for_pattern. O motivo não é paranoia. O Claude Code tem suas próprias ferramentas de arquivo e de shell, então a Serena deixa essas funções de lado e mantém o trabalho com símbolos.
💡 Excluir a ferramenta de shell da Serena não tira o poder de shell da sessão. A ferramenta Bash própria do Claude Code continua lá, mas ela passa pelos pedidos de permissão do Claude Code, que é onde você quer que essa decisão fique.
A Serena documenta uma forma de desativar os relatórios de uso anônimos: defina SERENA_USAGE_REPORTING=false no ambiente que inicia o servidor. Os servidores de linguagem são programas separados e, dependendo da linguagem, um deles pode precisar ser baixado na primeira vez que você o usar. Espere um pouco de atividade de rede numa primeira execução com uma nova linguagem, e confira um log de firewall se o seu ambiente for restrito.
A Serena consome tokens de duas formas. O custo fixo são as definições de ferramentas carregadas em toda sessão. O custo variável é o que as ferramentas retornam enquanto você trabalha. O primeiro é previsível, e o segundo depende de como você trabalha.
O projeto wrapper serena-slim estima que a Serena original carrega 29 ferramentas, que custam cerca de 23.878 tokens no Claude Code, e que a versão agrupada, com 18 operações, reduz isso para cerca de 11.874 tokens. Esse é um número divulgado pelo autor de um wrapper de terceiros, não uma medição da sua instalação. No contexto claude-code, seis ferramentas já estão excluídas, então o seu número provavelmente será menor que o da versão original.
Meça você mesmo. Rode /context no Claude Code antes de adicionar o servidor e de novo depois, e compare a linha das ferramentas MCP. Essa única comparação vale mais do que qualquer estimativa deste artigo.
Para entender por que o custo fixo importa, aqui vai uma conta, não uma medição. Suponha que as definições consumam 12.000 tokens e que você abra 20 sessões por dia. São 240.000 tokens de sobrecarga antes de qualquer pergunta ser feita. Corte o payload pela metade e você economiza o mesmo valor de novo, todos os dias, tenha ou não a Serena justificado seu lugar naquela sessão.
O custo variável se divide em três partes:
no-onboarding e no-memories desligam isso quando você quer uma sessão enxuta.Os contextos são escolhidos na inicialização e não podem mudar no meio da sessão. O padrão é desktop-app, que existe para um cliente diferente do Claude Code. Sem --context claude-code, espere ao mesmo tempo ferramentas de arquivo que duplicam as do Claude Code, uma ferramenta de shell e um payload de definições maior. Digite /mcp depois da configuração e compare a lista de ferramentas com as seis exclusões acima. Um único parâmetro resolve o custo de tokens e a exposição de segurança juntos.
O Claude Code também pode adiar as definições de ferramentas MCP e carregá-las sob demanda, em vez de na inicialização. Um texto de configuração liga isso com ENABLE_TOOL_SEARCH=true; confira as notas de versão do seu Claude Code, porque a chave pode ser diferente. Um wrapper enxuto adiciona mais um pacote de terceiros entre você e seu código. Pese isso contra os tokens economizados, já que a economia só importa se você confiar na camada extra.
O processo inteiro leva alguns minutos. uv é o único pré-requisito.
uv tool install -p 3.13 serena-agent
serena init
A Serena também traz um atalho, serena setup claude-code, para a mesma tarefa. Os comandos manuais abaixo mostram exatamente com o que você está concordando, por isso eu prefiro usá-los na primeira vez.
Para um único projeto, rode isto na pasta do projeto:
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
Para todos os projetos da máquina, a forma global é:
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd
Eu recomendo o comando por projeto. O Claude Code guarda isso no escopo local por padrão, então vale só para aquele projeto, enquanto a forma global ativa a Serena em qualquer pasta que você abrir, então uma sessão aberta por engano no diretório errado recebe as mesmas ferramentas de edição. Confira o resultado com claude mcp list, ou digite /mcp dentro do Claude Code. Se o servidor demorar para iniciar, aumente o tempo limite com export MCP_TIMEOUT=60000.
💡 No Windows, rode isto no PowerShell e troque
"$(pwd)"por"$PWD"se o shell reclamar. Mantenha o caminho do projeto sem aspas sobrando, já que um caminho errado faz a Serena ativar a pasta errada.
A própria documentação da Serena avisa que atualizações recentes do Claude Code e dos modelos reduziram a obediência do agente às instruções sobre as ferramentas da Serena, e que sessões longas podem se afastar delas. A solução é iniciar o Claude Code com uma substituição do prompt de sistema:
claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"
A documentação também recomenda com força lembretes em hooks em .claude/settings.json, com quatro comandos: remind, activate, cleanup e auto-approve. Leia o que auto-approve faz antes de conectá-lo. Qualquer coisa que aprove chamadas de ferramenta por você reduz os momentos em que você pode dizer não.
Faça isso na ordem. Cada etapa fornece as evidências para a seguinte.
A Serena lê as configurações de um arquivo global, ~/.serena/serena_config.yml (no Windows, %USERPROFILE%\.serena\serena_config.yml), e de um project.yml que o substitui para um projeto. Abra qualquer um com serena config edit. Para as primeiras sessões, defina isto no arquivo do projeto:
read_only: true
Nesse modo, a Serena pode ler arquivos, inspecionar a estrutura, buscar símbolos e criar índices, mas não pode gravar. As leituras são onde as ferramentas de símbolo economizam tokens, então você perde pouco ao começar aqui, e não abre mão de nada que não possa ligar depois.
A Serena serve um painel local, normalmente em http://localhost:24282/dashboard/index.html. O texto sobre segurança sugere rodar somente leitura por cerca de um dia e acompanhar: quais arquivos são tocados, quais ferramentas são chamadas e se os erros se repetem. Se uma ferramenta disparar sem que você esperasse, você descobre enquanto ela ainda é inofensiva.
Quando os logs parecerem limpos, permita as gravações e mantenha o shell excluído. Os nomes abaixo vêm do mesmo texto de terceiros, então confirme-os na lista de ferramentas da versão da sua Serena:
read_only: false
included_optional_tools:
- edit_file
excluded_tools:
- execute_shell_command
Faça commit de uma árvore git limpa antes de cada sessão. Depois, git diff mostra exatamente o que a Serena alterou, e um único git restore desfaz uma edição ruim. Esse hábito vale mais do que qualquer configuração acima.
Uma lista curta para a primeira semana:
/mcp lista a Serena como conectada e não mostra nenhuma ferramenta de shell./context e anote o número das ferramentas MCP.read_only: true até o painel parecer entediante.git diff depois de cada sessão que gravou arquivos..serena uma vez e leia o que as memórias contêm.Uma segunda opinião sobre a sua configuração custa pouco. O Claude Sonnet 5 no PicassoIA lê código, configurações e capturas de tela, então pode revisar seu project.yml antes de você aplicá-lo.
low, que é rápido e barato. Use high para uma configuração com muitas ferramentas, e xhigh ou max só para uma configuração emaranhada.max_image_resolution tem 0,5 megapixel, o que basta para um gráfico legível.💡 Trate a resposta como um comentário de revisor, não como um veredito. Para outro ângulo, rode o mesmo prompt no Claude Fable 5 ou no GPT 5.6 Sol e compare onde eles divergem.
| Erro | O que acontece | Correção |
|---|---|---|
Pular --context claude-code | Ferramentas de arquivo duplicadas, uma ferramenta de shell e uma carga maior de tokens | Sempre passe o parâmetro |
--project-from-cwd global em todo lugar | Ferramentas de edição ativas em qualquer pasta que você abrir | Registre por projeto |
Conectar auto-approve sem olhar | Menos chances de recusar uma chamada arriscada | Leia o hook e então decida |
| Rodar de uma URL git sem fixar versão | Você roda o que a branch tiver naquele dia | Instale o pacote ou fixe uma tag |
Nunca conferir /context | O custo em tokens continua um palpite | Meça antes e depois |
Fazer commit de .serena sem olhar | Arquivos de memória e anotações vão parar em um repositório compartilhado | Abra a pasta primeiro |
| Confiar em uma sessão longa | O agente se afasta das ferramentas da Serena | Use os hooks e reinicie |
Se você escreve sobre suas ferramentas, conhece a outra metade do trabalho: READMEs, posts de blog e slides de palestras precisam de visuais que pareçam pertencer ao conjunto. O Picasso IA reúne os modelos de imagem em um só lugar, então você pode testar um prompt, alterá-lo e comparar resultados em minutos. Para cenas fotorrealistas, comece com o Seedream 4.5 ou o FLUX 1.1 Pro, e depois explore todos os outros em picassoia.com/en/all-models.
Descreva uma cena real com uma lente, uma direção de luz e uma textura, rode e ajuste um detalhe por vez. Trate o primeiro resultado como um rascunho, porque o terceiro costuma se aproximar mais do que você imaginou. Abra um modelo, digite um prompt e veja o que volta.
Escolha seu idioma
