Serena MCP gives Claude Code symbol-level tools, and with them comes real write access. See what the shell tool can do, how many tokens the tool definitions cost, the exact setup commands, and a read-only rollout that keeps your repository safe.
Serena MCP is safe to run if you treat it like any tool that can edit your code, because that is exactly what it is. The server runs on your own machine, the source is public, and in the claude-code context its shell tool is switched off. The real questions are narrower: what can it write to disk, what does it send out, and how many tokens does it burn before you type a single prompt? This article answers all three with exact commands, config names and a rollout order you can follow today.
A quick note on sources. The commands and settings below come from Serena's repository and its client setup page. The token figures come from a third-party wrapper and a security write-up, and I label them as such. Measure your own setup before you trust any number, mine included.
Serena, built by Oraios, is an MCP server that hands a coding agent IDE-style tools. Instead of reading whole files and matching text, the agent asks for symbols: classes, functions, methods and the places that reference them. The repository lists retrieval tools (find symbol, symbol overview, find referencing symbols), symbolic editing (replace a symbol body, insert before or after a symbol), regex search, file operations, shell execution and a persistent memory system. Language support runs past 40 languages through language servers.
Who gets value from this? Anyone working in a repository too large to hold in a single prompt: multi-module backends, monorepos, long-lived apps where a rename touches thirty files. If your project is a handful of scripts, the plain tools in Claude Code are already enough, and adding a server mostly adds surface area. Match the tool to the size of the problem before you start asking whether it is safe.
A plain agent finds a function by searching text, then reads the surrounding files to be sure it has the right one. Serena asks a language server instead, so the answer is the definition itself, not a pile of files.
| Task | Plain file tools | Serena tools |
|---|---|---|
| Find a function | Search text, read whole files | Find symbol returns the definition |
| See who calls it | Search and guess | Find referencing symbols |
| Edit a method | Rewrite a text block | Replace symbol body |
| Orient in a file | Read the full file | Symbol overview |
Claude Code launches Serena as a local process, and the language servers run locally too. Serena is not a hosted service, and as far as the public docs show, there is no Serena cloud that receives your repository. There is one catch worth saying out loud: whatever a Serena tool returns lands in Claude's context, and that context goes to the model API like every other tool result. Serena does not make a session more private. It makes the reads smaller and more precise.
For most developers working on their own repositories, yes, with conditions. The risks are ordinary ones, and each has a control you can set in minutes.
Start from the threat model. You are not worried about a stranger breaking into Serena. You are worried about three quieter things: the agent changing files you did not mean to change, the agent running a command you did not mean to run, and text inside a file persuading the agent to do either one. That last one is prompt injection, and it applies to every tool that reads untrusted content. A cloned repository, a downloaded dependency or a pasted issue can contain a sentence addressed to the model instead of to you. A short tool list and a permission prompt on writes are the best defense, because they limit what a hijacked instruction can reach.
| Area | Risk | Control |
|---|---|---|
| File writes | Symbol edits change files on disk | read_only: true, a clean git tree, diff review |
| Shell | execute_shell_command runs arbitrary commands | Excluded in the claude-code context, plus excluded_tools |
| Telemetry | Anonymous usage reporting | SERENA_USAGE_REPORTING=false |
| Supply chain | Running straight from a git URL | Install the package or pin a tag |
| Prompt injection | Text inside a repo can instruct the agent | Permission prompts, small tool list |
| License | GPL-3.0-or-later application code | Read it before you redistribute |
Serena's application code is GPL-3.0-or-later, and the bundled SolidLSP layer is MIT. Open code means you can read exactly what runs on your machine, which is a real safety property. Running a GPL tool on your own repository does not change your repository's license. The license starts to matter when you modify Serena and ship it to other people, and at that point you should ask a lawyer rather than a blog.
The sharpest tool in the box is execute_shell_command. A security write-up on Serena calls it the most dangerous capability, with unintended file deletion, leaked credentials and broken system configuration as the failure modes, and suggests keeping it for CI environments rather than local work.
The claude-code context already removes it. That context excludes six tools: create_text_file, read_file, execute_shell_command, find_file, list_dir and search_for_pattern. The reason is not paranoia. Claude Code has its own file and shell tools, so Serena stands down on those and keeps the symbol work.
💡 Excluding Serena's shell tool does not remove shell power from the session. Claude Code's own Bash tool is still there, but it runs through Claude Code's permission prompts, which is where you want that decision to live.
Serena documents an opt-out for anonymous usage reporting: set SERENA_USAGE_REPORTING=false in the environment that launches the server. Language servers are separate programs, and depending on the language, one may need to be fetched the first time you use it. Expect a little network activity on a first run in a new language, and check a firewall log if your environment is strict.
Serena costs tokens in two ways. The fixed cost is the tool definitions that load into every session. The variable cost is what the tools return while you work. The first is predictable, and the second depends on how you work.
The wrapper project serena-slim estimates that the original Serena loads 29 tools worth roughly 23,878 tokens in Claude Code, and that its grouped version, with 18 operations, drops that to about 11,874 tokens. That is a vendor figure for a third-party wrapper, not a measurement of your install. In the claude-code context six tools are already excluded, so your number is likely lower than the original.
Measure it yourself. Run /context in Claude Code before you add the server and again after, and compare the MCP tools line. That one comparison beats any estimate in this article.
To see why the fixed cost matters, here is arithmetic, not a measurement. Say the definitions take 12,000 tokens and you open 20 sessions a day. That is 240,000 tokens of overhead before a single question gets asked. Cut the payload in half and you save the same amount again, every day, whether or not Serena earns its place that session.
The variable cost splits three ways:
no-onboarding and no-memories modes switch that off when you want a lean session.Contexts are chosen at startup and cannot change mid-session. The default is desktop-app, which exists for a different client than Claude Code. Without --context claude-code, expect file tools that duplicate Claude Code's own, a shell tool, and a bigger definition payload, all at once. Type /mcp after setup and compare the tool list against the six exclusions above. One flag fixes the token cost and the safety exposure together.
Claude Code can also defer MCP tool definitions and load them on demand instead of at startup. One setup write-up turns this on with ENABLE_TOOL_SEARCH=true; check the release notes for your Claude Code version, because the switch may differ. A slim wrapper adds one more third-party package between you and your code. Weigh that against the tokens saved, since the savings only matter if you trust the extra layer.
The whole process takes a few minutes. uv is the only prerequisite.
uv tool install -p 3.13 serena-agent
serena init
Serena also ships a shortcut, serena setup claude-code, for the same job. The manual commands below show you exactly what you are agreeing to, which is why I prefer them the first time.
For a single project, run this from the project folder:
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
For every project on the machine, the global form is:
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd
I recommend the per-project command. Claude Code stores it in local scope by default, so it applies to that project only, while the global form activates Serena on whichever folder you open, so a stray session in the wrong directory gets the same editing tools. Check the result with claude mcp list, or type /mcp inside Claude Code. If the server is slow to start, raise the timeout with export MCP_TIMEOUT=60000.
💡 On Windows, run these in PowerShell and swap
"$(pwd)"for"$PWD"if your shell complains. Keep the project path free of stray quotes, since a wrong path means Serena activates the wrong folder.
Serena's own docs warn that recent Claude Code and model updates have reduced how well the agent follows instructions about Serena's tools, and that long sessions can drift away from them. The workaround is to start Claude Code with a system prompt override:
claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"
The docs also strongly recommend reminder hooks in .claude/settings.json, with four commands: remind, activate, cleanup and auto-approve. Read what auto-approve does before you wire it in. Anything that approves tool calls for you reduces the number of moments where you can say no.
Do this in order. Each stage gives you evidence for the next one.
Serena reads settings from a global file, ~/.serena/serena_config.yml (on Windows, %USERPROFILE%\.serena\serena_config.yml), and from a project.yml that overrides it for one project. Open either with serena config edit. For the first sessions, set this in the project file:
read_only: true
In this mode Serena can read files, inspect structure, search symbols and build indexes, and it cannot write. Reads are where the symbol tools save tokens, so you lose little by starting here, and you give up nothing you cannot switch on later.
Serena serves a local dashboard, usually at http://localhost:24282/dashboard/index.html. The security write-up suggests running read-only for about a day and watching it: which files are touched, which tools get called, and whether errors repeat. If a tool fires that you did not expect, you found out while it was harmless.
When the logs look clean, allow writes and keep the shell excluded. The names below come from the same third-party write-up, so confirm them against your Serena version's tool list:
read_only: false
included_optional_tools:
- edit_file
excluded_tools:
- execute_shell_command
Commit a clean git tree before every session. Then git diff shows exactly what Serena changed, and one git restore undoes a bad edit. This habit is worth more than any setting above.
A short checklist for the first week:
/mcp lists Serena as connected and shows no shell tool./context and write down the MCP tools number.read_only: true until the dashboard looks boring.git diff after every session that wrote files..serena folder once and read what the memories contain.A second opinion on your config is cheap. Claude Sonnet 5 on PicassoIA reads code, config and screenshots, so it can review your project.yml before you apply it.
low, which is fast and cheap. Use high for a config with many tools, and xhigh or max only for a tangled one.max_image_resolution is 0.5 megapixels, which is enough for a readable chart.💡 Treat the answer as a reviewer's comment, not a verdict. For a different angle, run the same prompt through Claude Fable 5 or GPT 5.6 Sol and compare where they disagree.
| Mistake | What happens | Fix |
|---|---|---|
Skipping --context claude-code | Duplicate file tools, a shell tool and a larger token load | Always pass the flag |
Global --project-from-cwd everywhere | Editing tools active in any folder you open | Register per project |
Wiring in auto-approve blindly | Fewer chances to refuse a risky call | Read the hook, then decide |
| Running from a git URL unpinned | You run whatever the branch holds that day | Install the package or pin a tag |
Never checking /context | Token cost stays a guess | Measure before and after |
Committing .serena without a look | Memory files and notes get pushed to a shared repo | Open the folder first |
| Trusting a long session | The agent drifts from Serena's tools | Use the hooks and restart |
If you write about your tooling, you know the other half of the job: READMEs, blog posts and talk slides all need visuals that look like they belong. Picasso IA puts the image models in one place, so you can try a prompt, change it and compare results in minutes. For photorealistic scenes, start with Seedream 4.5 or FLUX 1.1 Pro, then browse everything else at picassoia.com/en/all-models.
Describe a real scene with a lens, a light direction and a texture, run it, and adjust one detail at a time. Treat the first result as a draft, because the third is usually closer to what you pictured. Open a model, type a prompt and see what comes back.
