Serena MCP da a Claude Code herramientas a nivel de símbolo, y con ellas llega un acceso real de escritura. Descubre qué puede hacer la herramienta de shell, cuántos tokens cuestan las definiciones de herramientas, los comandos exactos de configuración y un despliegue de solo lectura que protege tu repositorio.
Serena MCP es seguro de ejecutar si lo tratas como cualquier herramienta que puede editar tu código, porque eso es exactamente lo que es. El servidor se ejecuta en tu propia máquina, su código fuente es público y, en el contexto claude-code, su herramienta de shell está desactivada. Las preguntas reales son más concretas: qué puede escribir en disco, qué envía hacia fuera y cuántos tokens consume antes de que escribas un solo prompt. Este artículo responde a las tres con comandos exactos, nombres de configuración y un orden de despliegue que puedes seguir hoy mismo.
Una nota rápida sobre las fuentes. Los comandos y ajustes que aparecen abajo provienen del repositorio de Serena y de su página de configuración del cliente. Las cifras de tokens provienen de un wrapper de terceros y de un análisis de seguridad, y así lo indico. Mide tu propia configuración antes de fiarte de cualquier número, incluido el mío.
Serena, desarrollado por Oraios, es un servidor MCP que entrega a un agente de programación herramientas al estilo de un IDE. En lugar de leer archivos completos y buscar coincidencias de texto, el agente pide símbolos: clases, funciones, métodos y los lugares que los referencian. El repositorio enumera herramientas de búsqueda (find symbol, symbol overview, find referencing symbols), edición simbólica (reemplazar el cuerpo de un símbolo, insertar antes o después de un símbolo), búsqueda con regex, operaciones con archivos, ejecución de shell y un sistema de memoria persistente. El soporte supera los 40 lenguajes de programación mediante servidores de lenguaje.
¿Quién saca provecho de esto? Cualquiera que trabaje en un repositorio demasiado grande para caber en un solo prompt: backends con varios módulos, monorepos, aplicaciones de larga vida donde un renombrado afecta a treinta archivos. Si tu proyecto son un puñado de scripts, las herramientas básicas de Claude Code ya bastan, y añadir un servidor sobre todo aumenta la superficie expuesta. Ajusta la herramienta al tamaño del problema antes de preguntarte si es segura.
Un agente normal encuentra una función buscando texto y luego lee los archivos cercanos para asegurarse de que es la correcta. Serena, en cambio, consulta a un servidor de lenguaje, así que la respuesta es la propia definición, no un montón de archivos.
| Tarea | Herramientas de archivos normales | Herramientas de Serena |
|---|---|---|
| Encontrar una función | Buscar texto, leer archivos completos | Find symbol devuelve la definición |
| Ver quién la llama | Buscar y adivinar | Find referencing symbols |
| Editar un método | Reescribir un bloque de texto | Replace symbol body |
| Orientarse en un archivo | Leer el archivo completo | Symbol overview |
Claude Code lanza Serena como un proceso local, y los servidores de lenguaje también se ejecutan en local. Serena no es un servicio alojado y, según muestra la documentación pública, no existe una nube de Serena que reciba tu repositorio. Hay una salvedad que conviene decir en voz alta: todo lo que devuelve una herramienta de Serena llega al contexto de Claude, y ese contexto se envía a la API del modelo como cualquier otro resultado de herramienta. Serena no hace una sesión más privada. Hace que las lecturas sean más pequeñas y precisas.
Para la mayoría de los desarrolladores que trabajan en sus propios repositorios, sí, con condiciones. Los riesgos son los habituales, y cada uno tiene un control que puedes configurar en minutos.
Empieza por el modelo de amenazas. No te preocupa que un extraño entre en Serena. Te preocupan tres cosas más silenciosas: que el agente cambie archivos que no querías cambiar, que ejecute un comando que no querías ejecutar y que un texto dentro de un archivo lo convenza de hacer cualquiera de las dos cosas. Esa última es la inyección de prompts, y afecta a toda herramienta que lea contenido no confiable. Un repositorio clonado, una dependencia descargada o un issue pegado pueden contener una frase dirigida al modelo en lugar de a ti. Una lista corta de herramientas y un aviso de permiso en las escrituras son la mejor defensa, porque limitan hasta dónde puede llegar una instrucción secuestrada.
| Área | Riesgo | Control |
|---|---|---|
| Escrituras de archivos | Las ediciones simbólicas cambian archivos en disco | read_only: true, un árbol de git limpio, revisión de diffs |
| Shell | execute_shell_command ejecuta comandos arbitrarios | Excluida en el contexto claude-code, más excluded_tools |
| Telemetría | Reporte anónimo de uso | SERENA_USAGE_REPORTING=false |
| Cadena de suministro | Ejecutar directamente desde una URL de git | Instala el paquete o fija una etiqueta |
| Inyección de prompts | Un texto dentro del repo puede dar instrucciones al agente | Avisos de permiso, lista corta de herramientas |
| Licencia | Código de la aplicación GPL-3.0-or-later | Léelo antes de redistribuir |
El código de la aplicación de Serena es GPL-3.0-or-later, y la capa SolidLSP incluida es MIT. El código abierto significa que puedes leer exactamente lo que se ejecuta en tu máquina, lo cual es una propiedad de seguridad real. Ejecutar una herramienta GPL sobre tu propio repositorio no cambia la licencia de tu repositorio. La licencia empieza a importar cuando modificas Serena y se lo entregas a otras personas, y en ese punto conviene consultar a un abogado y no a un blog.
La herramienta más potente del conjunto es execute_shell_command. Un análisis de seguridad sobre Serena la califica como la capacidad más peligrosa, con el borrado accidental de archivos, la filtración de credenciales y la rotura de la configuración del sistema como modos de fallo, y sugiere reservarla para entornos de CI en lugar de trabajo local.
El contexto claude-code ya la elimina. Ese contexto excluye seis herramientas: create_text_file, read_file, execute_shell_command, find_file, list_dir y search_for_pattern. La razón no es paranoia. Claude Code tiene sus propias herramientas de archivos y de shell, así que Serena cede en esas funciones y conserva el trabajo simbólico.
💡 Excluir la herramienta de shell de Serena no quita potencia de shell a la sesión. La herramienta Bash propia de Claude Code sigue disponible, pero se ejecuta a través de los avisos de permiso de Claude Code, que es donde conviene que se tome esa decisión.
Serena documenta una opción de exclusión para el reporte anónimo de uso: define SERENA_USAGE_REPORTING=false en el entorno que lanza el servidor. Los servidores de lenguaje son programas independientes y, según el lenguaje, puede que haya que descargar uno la primera vez que lo uses. Espera algo de actividad de red en la primera ejecución con un lenguaje nuevo, y revisa el registro del firewall si tu entorno es estricto.
Serena consume tokens de dos maneras. El costo fijo son las definiciones de herramientas que se cargan en cada sesión. El costo variable es lo que devuelven las herramientas mientras trabajas. El primero es predecible, y el segundo depende de cómo trabajes.
El proyecto wrapper serena-slim estima que el Serena original carga 29 herramientas que suman unos 23.878 tokens en Claude Code, y que su versión agrupada, con 18 operaciones, baja eso a unos 11.874 tokens. Es una cifra del proveedor de un wrapper de terceros, no una medición de tu instalación. En el contexto claude-code ya se excluyen seis herramientas, así que tu número probablemente sea menor que el original.
Mídelo tú mismo. Ejecuta /context en Claude Code antes de añadir el servidor y otra vez después, y compara la línea de herramientas MCP. Esa única comparación vale más que cualquier estimación de este artículo.
Para ver por qué importa el costo fijo, aquí hay una aritmética, no una medición. Supongamos que las definiciones ocupan 12.000 tokens y abres 20 sesiones al día. Eso son 240.000 tokens de sobrecarga antes de hacer una sola pregunta. Si reduces a la mitad la carga, ahorras la misma cantidad cada día, ya sea que Serena se gane su lugar en esa sesión o no.
El costo variable se divide en tres partes:
no-onboarding y no-memories desactivan eso cuando quieres una sesión ligera.Los contextos se eligen al iniciar y no pueden cambiar a mitad de sesión. El predeterminado es desktop-app, que existe para un cliente distinto a Claude Code. Sin --context claude-code, espera herramientas de archivos que duplican las de Claude Code, una herramienta de shell y una carga de definiciones más grande, todo a la vez. Escribe /mcp después de la configuración y compara la lista de herramientas con las seis exclusiones de arriba. Una sola opción corrige a la vez el costo en tokens y la exposición de seguridad.
Claude Code también puede diferir las definiciones de herramientas MCP y cargarlas bajo demanda en lugar de al inicio. Un artículo sobre configuración activa esto con ENABLE_TOOL_SEARCH=true; revisa las notas de la versión de Claude Code que uses, porque el interruptor puede ser diferente. Un wrapper ligero añade un paquete de terceros más entre tú y tu código. Sopésalo frente a los tokens ahorrados, ya que el ahorro solo importa si confías en esa capa extra.
Todo el proceso lleva unos pocos minutos. uv es el único requisito previo.
uv tool install -p 3.13 serena-agent
serena init
Serena también incluye un atajo, serena setup claude-code, para la misma tarea. Los comandos manuales de abajo te muestran exactamente qué estás aceptando, por eso los prefiero la primera vez.
Para un solo proyecto, ejecuta esto desde la carpeta del proyecto:
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
Para todos los proyectos de la máquina, la forma global es:
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd
Recomiendo el comando por proyecto. Claude Code lo guarda en el ámbito local de forma predeterminada, así que se aplica solo a ese proyecto, mientras que la forma global activa Serena en cualquier carpeta que abras, de modo que una sesión abierta por error en el directorio equivocado recibe las mismas herramientas de edición. Comprueba el resultado con claude mcp list, o escribe /mcp dentro de Claude Code. Si el servidor tarda en arrancar, aumenta el tiempo de espera con export MCP_TIMEOUT=60000.
💡 En Windows, ejecuta esto en PowerShell y sustituye
"$(pwd)"por"$PWD"si tu shell da error. Evita comillas sobrantes en la ruta del proyecto, ya que una ruta incorrecta hace que Serena active la carpeta equivocada.
La documentación de Serena advierte que las actualizaciones recientes de Claude Code y de los modelos han reducido lo bien que el agente sigue las instrucciones sobre las herramientas de Serena, y que las sesiones largas pueden alejarse de ellas. La solución alternativa es iniciar Claude Code con una anulación del prompt del sistema:
claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"
La documentación también recomienda encarecidamente hooks de recordatorio en .claude/settings.json, con cuatro comandos: remind, activate, cleanup y auto-approve. Lee qué hace auto-approve antes de conectarlo. Cualquier cosa que apruebe las llamadas a herramientas por ti reduce los momentos en los que puedes decir que no.
Hazlo en orden. Cada etapa te da pruebas para la siguiente.
Serena lee la configuración de un archivo global, ~/.serena/serena_config.yml (en Windows, %USERPROFILE%\.serena\serena_config.yml), y de un project.yml que lo anula para un proyecto. Abre cualquiera de los dos con serena config edit. Para las primeras sesiones, define esto en el archivo del proyecto:
read_only: true
En este modo Serena puede leer archivos, inspeccionar la estructura, buscar símbolos y construir índices, pero no puede escribir. Es al leer cuando las herramientas de símbolos ahorran tokens, así que pierdes poco si empiezas aquí, y no renuncias a nada que no puedas activar más adelante.
Serena sirve un panel local, normalmente en http://localhost:24282/dashboard/index.html. El análisis de seguridad sugiere ejecutar en solo lectura durante un día aproximadamente y vigilarlo: qué archivos se tocan, qué herramientas se invocan y si los errores se repiten. Si se dispara una herramienta que no esperabas, lo descubrirás cuando todavía es inofensiva.
Cuando los registros se vean limpios, permite las escrituras y mantén excluida la shell. Los nombres de abajo provienen del mismo análisis de terceros, así que confírmalos con la lista de herramientas de tu versión de Serena:
read_only: false
included_optional_tools:
- edit_file
excluded_tools:
- execute_shell_command
Haz un commit de un árbol de git limpio antes de cada sesión. Después, git diff muestra exactamente lo que cambió Serena, y un único git restore deshace una mala edición. Este hábito vale más que cualquier ajuste de arriba.
Una lista breve para la primera semana:
/mcp muestra Serena como conectado y no muestra ninguna herramienta de shell./context y anota el número de herramientas MCP.read_only: true hasta que el panel se vuelva aburrido.git diff después de cada sesión que haya escrito archivos..serena una vez y lee lo que contienen las memorias.Una segunda opinión sobre tu configuración es barata. Claude Sonnet 5 en PicassoIA lee código, configuración y capturas de pantalla, así que puede revisar tu project.yml antes de que lo apliques.
low, que es rápido y barato. Usa high para una configuración con muchas herramientas, y xhigh o max solo para una enredada.max_image_resolution es de 0,5 megapíxeles, suficiente para un gráfico legible.💡 Trata la respuesta como el comentario de un revisor, no como un veredicto. Para otro enfoque, pasa el mismo prompt por Claude Fable 5 o GPT 5.6 Sol y compara en qué puntos discrepan.
| Error | Qué pasa | Solución |
|---|---|---|
Omitir --context claude-code | Herramientas de archivos duplicadas, una herramienta de shell y una carga de tokens mayor | Pasa siempre la opción |
--project-from-cwd global en todas partes | Herramientas de edición activas en cualquier carpeta que abras | Regístralo por proyecto |
Conectar auto-approve a ciegas | Menos oportunidades de rechazar una llamada arriesgada | Lee el hook y luego decide |
| Ejecutar desde una URL de git sin fijar | Ejecutas lo que tenga la rama ese día | Instala el paquete o fija una etiqueta |
No comprobar nunca /context | El costo en tokens sigue siendo una suposición | Mide antes y después |
Hacer commit de .serena sin revisarlo | Los archivos de memoria y las notas se suben a un repo compartido | Abre la carpeta primero |
| Confiar en una sesión larga | El agente se aleja de las herramientas de Serena | Usa los hooks y reinicia |
Si escribes sobre tus herramientas, conoces la otra mitad del trabajo: los README, las entradas de blog y las diapositivas de charlas necesitan imágenes que parezcan de su sitio. Picasso IA reúne los modelos de imagen en un solo lugar, así que puedes probar un prompt, modificarlo y comparar resultados en minutos. Para escenas fotorrealistas, empieza con Seedream 4.5 o FLUX 1.1 Pro, y luego explora el resto en picassoia.com/en/all-models.
Describe una escena real con un objetivo, una dirección de luz y una textura, ejecútala y ajusta un detalle a la vez. Trata el primer resultado como un borrador, porque el tercero suele acercarse más a lo que imaginabas. Abre un modelo, escribe un prompt y mira qué devuelve.
Elige tu idioma
