Como Usar o Servidor Serena MCP

Olá! Cansado de gastar dinheiro com ferramentas de codificação de IA? Vamos falar sobre o Serena MCP Server, uma joia gratuita e de código aberto que transforma seu LLM favorito em uma potência de codificação, tudo sem estourar o orçamento. Construído pela Oraios AI, o Serena permite que você codifique de forma mais inteligente com ferramentas como Claude ou modelos de peso aberto, e a melhor parte? Você pode usá-lo gratuitamente! Neste guia, abordaremos o que é o Serena, como instalá-lo para um projeto com Claude Code e como configurar o Serena MCP Server no Claude Desktop e no Cursor. Vamos mergulhar e economizar algumas taxas de assinatura!

O Que É o Serena MCP Server?

O Serena MCP Server é um kit de ferramentas gratuito e de código aberto da Oraios AI que transforma qualquer modelo de linguagem grande (LLM) em um agente de codificação completo. Ele usa o Protocolo de Contexto de Modelo (MCP) e o Protocolo de Servidor de Linguagem (LSP) para fornecer recursos semelhantes a IDEs, como análise semântica de código, edição em nível de símbolo e suporte a várias linguagens (Python, JavaScript, Java e muito mais). Seja para refatorar código, analisar grandes bases de código ou prototipar, o Serena lida com tudo — desde o planejamento até o commit de alterações no controle de versão.

Por que é incrível? O Serena nasceu da frustração com assinaturas caras de IDEs como Cursor ou Windsurf e ferramentas pesadas em API como Claude Code ou Cline. A Oraios AI queria uma alternativa gratuita que funcionasse com os LLMs que você já possui, como o Claude da Anthropic (mesmo na camada gratuita!) ou modelos de peso aberto via Agno. É o presente deles para a comunidade de desenvolvedores, e eles o usam diariamente. Além disso, é licenciado pelo MIT, então você pode personalizá-lo à vontade.

Instalando o Serena em um Projeto com Claude Code

Vamos colocar o Serena MCP Server para funcionar em seu projeto usando o Claude Code, um assistente de codificação popular que suporta servidores MCP gratuitamente. Veja como configurá-lo:

Passo 1: Instalar Pré-requisitos

1. Instalar uv:

• O Serena usa uv (um gerenciador de pacotes Python) para funcionar. Instale-o via:

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

# Para usuários Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Ou use o Homebrew: brew install uv.

2. Clonar o Repositório do Serena:

• Obtenha o código-fonte do Serena do GitHub:

git clone https://github.com/oraios/serena
cd serena

3. Configurar Ambiente:

• Copie o arquivo de ambiente de exemplo:

cp .env.example .env

• Nenhuma chave de API é necessária para a camada gratuita do Claude, mas se estiver usando um modelo pago, adicione sua chave ao .env.

Passo 2: Configurar o Serena para Claude Code

1. Iniciar o Servidor MCP:

• Execute o servidor MCP do Serena diretamente do repositório:

uv run serena start-mcp-server

Isso inicia um servidor local com um painel web em http://localhost:24282/dashboard/index.html para logs e desligamento.

2. Adicionar Serena ao Claude Code:

• No seu terminal, adicione o Serena como um servidor MCP ao Claude Code:

claude mcp add-json "serena" '{"command":"uvx","args":["--from","git+https://github.com/oraios/serena","serena-mcp-server"]}'

Isso informa ao Claude Code para usar o servidor MCP do Serena sem instalação local.

3. Testar:

• Abra o Claude Code, inicie uma nova conversa e digite:

Analise minha base de código Python em ./src.

• O Serena escaneará seu projeto, armazenará memórias em .serena/memories/ e fornecerá uma análise detalhada. Tente:

Refatore main.py para usar async/await.

• Veja o Serena sugerir mudanças de código precisas!

Solução de Problemas

• Servidor Não Iniciando? Certifique-se de que o uv esteja instalado e o arquivo .env configurado. Verifique os logs do painel.
• Erros no Claude Code? Verifique a sintaxe do comando MCP e reinicie o Claude Code.
• Problemas de Permissões? Use caminhos absolutos (ex: /caminho/para/serena) para evitar erros de caminho relativo.

Usando o Serena MCP Server no Claude Desktop

O Claude Desktop é outra ótima maneira de usar o Serena MCP Server gratuitamente, aproveitando a camada gratuita do Claude. Veja como conectá-lo:

Passo 1: Configurar o Servidor MCP

1. Executar o Servidor MCP do Serena:

• No diretório do repositório do Serena, inicie o servidor:

uv run serena start-mcp-server

Ou use o Docker (Experimental) para uma configuração mais limpa:

docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena start-mcp-server --transport stdio

Substitua /path/to/your/projects pelo caminho absoluto do seu projeto.

2. Editar a Configuração do Claude Desktop:

• Abra o arquivo de configuração do Claude Desktop:
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Adicione o servidor MCP do Serena:

{
  "mcpServers": {
    "serena": {
      "command": "/path/to/uv",
      "args": ["run", "--directory", "/path/to/serena", "serena-mcp-server"]
    }
  }
}

Substitua /path/to/uv e /path/to/serena pelos caminhos reais (use barras invertidas duplas \\ no Windows).

3. Reiniciar o Claude Desktop:

• Feche e reabra o Claude Desktop. Você verá um ícone de martelo indicando que as ferramentas do Serena estão ativas.

Passo 2: Testar o Serena no Claude Desktop

1. Iniciar uma Conversa:

• No Claude Desktop, digite:

Resuma meu projeto em ./myproject.

• O Serena analisará sua base de código e retornará um resumo, usando sua compreensão semântica alimentada por LSP.

2. Experimentar Tarefas de Codificação:

• Pergunte:

Corrija os bugs em src/app.js com base nos logs.

• O Serena sugerirá correções, extraindo informações dos logs e de sua memória de projeto em .serena/memories/.

3. Verificar o Painel:

• Visite http://localhost:24282/dashboard/index.html para monitorar logs ou desligar o servidor.

Dicas

• Habilitar Logs: Em myproject.yml, defina show_logs: true para facilitar a depuração.
• Controle de Versão: Adicione .serena ao .gitignore para evitar o commit de arquivos de memória.
• Segurança: Evite execute_shell_command no modo Agno sem confirmação para prevenir ações indesejadas.

Usando o Serena MCP Server no Cursor

O Cursor é uma IDE elegante alimentada por IA, e você pode usar o Serena MCP Server com o Cursor globalmente ou por projeto. Veja como:

Passo 1: Configurar o Servidor MCP do Serena

1. Iniciar o Servidor:

• Como antes, execute:

uv run serena start-mcp-server

Ou use o comando Docker da seção Claude Desktop.

2. Configurar o Cursor Globalmente:

• Abra ~/.cursor/mcp.json (na seção "Ferramentas e Integrações"):

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

Isso torna o Serena disponível em todos os projetos do Cursor.

3. Ou Configurar por Projeto:

• Na raiz do seu projeto, crie .cursor/mcp.json com a mesma configuração acima.

4. Reiniciar o Cursor:

• Feche e reabra o Cursor para aplicar as alterações.

Passo 2: Testar o Serena no Cursor

1. Abrir o Painel de Chat do Cursor:

• Em um projeto, abra o painel de chat e digite:

Gerar uma API REST em src/api.py.

• O Serena criará o código, respeitando a estrutura do seu projeto.

2. Refatorar Código:

• Destaque o código, pressione Ctrl+L (ou Cmd+L no macOS) e digite:

Otimize esta função para desempenho.

• O Serena sugerirá melhorias, mas observe que o modo de Edição pode ser limitado sem uma assinatura Pro.

3. Verificar Logs:

• Use o painel web (http://localhost:24282/dashboard/index.html) para solucionar problemas.

Por Que Usar o Serena MCP Server?

O Serena MCP Server é um salva-vidas para desenvolvedores cansados de custos de assinatura. Veja por que ele é incrível:

• Grátis para Sempre: Funciona com a camada gratuita do Claude ou modelos de peso aberto via Agno, sem necessidade de chaves de API.
• Recursos Poderosos: Recuperação de código semântica, edições em nível de símbolo e suporte a várias linguagens rivalizam com ferramentas pagas como o Cursor.
• Amigável à Privacidade: Executa localmente, mantendo sua base de código fora de servidores de terceiros.
• Impulsionado pela Comunidade: Com mais de 2.9 mil estrelas no GitHub e desenvolvimento ativo, o Serena está melhorando rapidamente.

Os usuários estão entusiasmados com o Serena, com alguns chamando-o de “a configuração de codificação mais forte” quando combinado com o Claude. Seja você um desenvolvedor solo ou parte de uma equipe, o Serena permite que você cancele essas assinaturas caras e codifique de forma mais inteligente. Em breve, o ChatGPT Desktop poderá suportar servidores MCP, expandindo ainda mais suas opções.

Conclusão

O Serena MCP Server é o seu bilhete para uma codificação gratuita e alimentada por IA com ferramentas como Claude Code, Claude Desktop e Cursor. Desde a instalação do Serena até a execução em seu editor favorito, agora você está equipado para lidar com tarefas de codificação sem dores de cabeça de assinatura. Experimente, explore seu painel web e me diga nos comentários como você está usando o Serena para impulsionar seu fluxo de trabalho!