tiennm99/serena
1
0 Fork 0
mirror of https://github.com/tiennm99/serena.git synced 2026-10-15 12:14:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Major enhancement in client connection documentation

Browse Source 
Added new contexts and extended some older ones to exclude more basic tool
This commit is contained in:
Michael Panchenko committed 2026-04-10 11:05:18 +02:00
1 parent 1a4b1f61b2
commit 0c945e08a4
9 files changed
+394 -117
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/02-usage/030_clients.md
+258 -117
View File
@@ -3,13 +3,6 @@
In the following, we provide general instructions on how to connect Serena to your MCP-enabled client,
as well as specific instructions for popular clients.
:::{note}
The configurations we provide for particular clients below will run the latest version of Serena
using the `stdio` protocol with `uvx`.
Adapt the commands to your preferred way of [running Serena](020_running), adding any additional
command-line arguments as needed.
:::
(clients-general-instructions)=
## General Instructions
@@ -47,14 +40,9 @@ A key mechanism for this is to use the appropriate [context](#contexts) when sta
(clients-common-pitfalls)=
### Common Pitfalls
**Escaping Paths Correctly**.
Note that if your client configuration uses JSON, special characters (like backslashes) need to be escaped properly.
In particular, if you are specifying paths containing backslashes on Windows
(note that you can also just use forward slashes), be sure to escape them correctly (`\\`).
**Discoverability of `uvx`**.
Your client may not find the `uvx` command, even if it is on your system PATH.
In this case, a workaround is to provide the full path to the `uvx` executable.
**Discoverability of the `serena`**.
Your client may not find the `serena` CLI command, even if it is on your system PATH.
In this case, a workaround is to provide the full path to the `serena` executable.
**Environment Variables**.
Some language servers may require additional environment variables to be set (e.g. F# on macOS with Homebrew),
@@ -71,42 +59,63 @@ object, e.g.
}
```
## Copilot in JetBrains
Open the settings of your JetBrains IDE and go to Tools / GitHub Copilot / Model Context Protocol (MCP). Then click
on the Configure button. This will open your global `mcp.json` file, where you can add the following entry for Serena:
```json
{
"servers": {
"serena": {
"type": "stdio",
"command": "serena",
"args": [
"start-mcp-server",
"--context=jb-copilot-plugin"
]
}
}
}
```
**Verification.**
Open Copilot, switch to Agent mode, and click on the configure tools button. You should see Serena's tools in the list and be able to start
the Serena server there (you do not generally have to start Serena in the future, Copilot will start the server by itself). If the server is shown as running, Copilot is successfully connected to Serena. Most models will understand how to use Serena's tools out of the box, but for some models you may have to prompt "Activate the current project with Serena and read initial instructions" in the beginning of the chat.
**Recommended Configuration**.
The `jb-copilot-plugin` context (see above) comes with our recommended subset of Serena's tools for Copilot in JetBrains IDEs. We also
recommend *disabling* the following built-in tools for optimal performance:
replace_string_in_file, apply_patch, list_dir, file_search, grep_search. Note that running subagents may not use MCP servers, consider deactivating the run_subagent tool as well.
Serena offers better alternatives to these basic tools. If you do prefer to use the built-in tools instead,
you should disable corresponding Serena tools instead to prevent context bloat.
We also recommend marking Serena's tools as approved so you don't have to manually approve them in agent sessions.
You can do this in Tools / GitHub Copilot / Chat, where at the bottom you can click on the Configure button for MCP tool auto-approval.
## Claude Code
Serena is a great way to make Claude Code both cheaper and more powerful!
:::{note}
Serena might take some time to start up, especially on the first run.
To make sure that enough time is available for the server to start,
set `MCP_TIMEOUT` to a sufficiently high value (e.g. by adding `export MCP_TIMEOUT=60000` to your shell profile)
before starting Claude Code.
Confirm that Claude Code is connected to Serena by running the `/mcp` command and by reconnecting, if necessary.
:::
To add Serena to Claude Code, you can simply run `serena setup claude-code`. Alternatively, follow the instructions below.
**Global Configuration**. To add the Serena MCP server for all your projects, use the user-level configuration of claude code and the `--project-from-cwd` flag:
```shell
claude mcp add --scope user serena -- uvx --python 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --context=claude-code --project-from-cwd
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd
```
**Per-Project Configuration.** Alternatively, to add Serena only for the current project in the current directory,
use the command:
```shell
claude mcp add serena -- uvx --python 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
```
Note:
* We use the `claude-code` context to disable unnecessary tools (avoiding duplication
with Claude Code's built-in capabilities).
* We specify the current directory as the project directory with `--project "$(pwd)"`, such
that Serena is configured to work on the current project from the get-go, following
Claude Code's mode of operation.
Whenever you start Claude Code, Serena will search up from the current directory for `.serena/project.yml` or `.git` markers,
activating the containing directory as the project (if any).
This mechanism makes it suitable for a single global MCP configuration.
**Verification.**
Confirm that Claude Code is connected to Serena by running the `/mcp` command and by reconnecting, if necessary.
If Serena fails to start fast enough, you should set `MCP_TIMEOUT` to a sufficiently high value
(e.g. by adding `export MCP_TIMEOUT=60000` to your shell profile)
**Maximum Token Efficiency.** To maximize token efficiency, you may want to use Claude Code's
*on-demand tool loading* feature, which is supported since at least v2.0.74 of Claude Code.
@@ -124,64 +133,173 @@ set ENABLE_TOOL_SEARCH=true && claude
```
in Windows CMD to launch Claude Code.
## VSCode
**Hooks.**
Claude Code's agent can sometimes drift away from using MCP tools during long sessions, falling back
to built-in tools or forgetting to load Serena's instructions. Serena provides hook commands that
automatically remind the agent to use Serena's tools when appropriate.
While serena can be directly installed from the GitHub MCP server registry, we recommend to set it up manually
(at least for now, until the configuration there has been improved). Just paste the following into
`<your_project>/.vscode/mcp.json`, or edit the entry after using the option `install into workspace`:
:::{note}
Hooks are an **alpha feature** that we provide to overcome context drift in several agent harnesses
(where agents, especially those powered by Anthropic models, may forget to load and use MCP tools or
fail to read MCP instructions).
:::
To set up hooks, add the following to your Claude Code settings file
(`.claude/settings.json` in your project directory, or `~/.claude/settings.json` globally):
All hooks below are opt-in — include only the ones you want. Add the following to your
Claude Code settings file (`.claude/settings.json` in your project directory, or
`~/.claude/settings.json` globally):
```json
{
"servers": {
"oraios/serena": {
"type": "stdio",
"command": "uvx",
"args": [
"-p",
"3.13",
"--from",
"git+https://github.com/oraios/serena",
"serena",
"start-mcp-server",
"--context",
"ide",
"--project",
"${workspaceFolder}"
]
"hooks": {
"PreToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "serena-hooks remind --client=claude-code"
}
]
},
{
"matcher": "mcp__serena__*",
"hooks": [
{
"type": "command",
"command": "serena-hooks auto-approve --client=claude-code"
}
]
}
],
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "serena-hooks activate --client=claude-code"
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "serena-hooks cleanup --client=claude-code"
}
]
}
]
}
},
"inputs": []
}
```
## Codex
The hooks will:
Serena works with OpenAI's Codex CLI and app out of the box, but you have to use the `codex` context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.).
- **`remind`**: Nudge the agent to use Serena's symbolic tools when it makes too many consecutive
`grep` or `read_file` calls without using any Serena tools in between.
- **`activate`**: Prompt the agent to activate the project and read Serena's instructions at session start.
- **`cleanup`**: Clean up hook session data when the session ends.
- **`auto-approve`**: Auto-approve Serena tool calls whenever Claude Code is in `acceptEdits` mode,
so blanket edit approvals cover Serena's destructive tools (e.g. `replace_symbol_body`,
`rename_symbol`) instead of prompting on every call.
Add a [run command](020_running) to `~/.codex/config.toml` to configure Serena for all Codex sessions;
create the file if it does not exist.
For example, when using `uvx`, add the following section:
For more details on Claude Code's hook system, see the
[Claude Code hooks documentation](https://code.claude.com/docs/en/hooks).
## VSCode
You can add Serena to VSCode by running the MCP: Add Server command.
In that dialogue, select the Command (stdio) option. You can decide between installing it globally
or in the workspace (only for the currently open project), and the command you should enter depends on that choice.
(You will be asked to choose after entering the mcp run command.)
**Global.** (Recommended)
Enter `serena start-mcp-server --context=vscode`. Unfortunately, due to a [bug in VSCode](https://github.com/microsoft/vscode/issues/245905),
in this setting Serena won't be able to activate the project automatically. You will have to remember to prompt
"Activate the current dir as project using serena" at the start of each session.
**Workspace.**
Enter `serena start-mcp-server --context=vscode --project ${workspaceFolder}`. This will allow Serena to automatically activate the project,
with the downside that you will have to add Serena to each project you want to use it in.
In both cases, proceed to enter Serena as the name, then select either global or workspace.
**Verification.**
You should be able to see Serena in the tools overview in the AI Chat window.
**Hooks.**
VSCode's Copilot agent can sometimes over-rely on basic tools like `read_file` and `grep_search` instead of
using Serena's more efficient symbolic tools. You can use Serena's hook commands to automatically correct
for this — the hooks will simply remind the agent to use Serena's tools when appropriate.
:::{note}
Hooks are an **alpha feature** that we provide to overcome context drift in several agent harnesses
(where agents, especially those powered by Anthropic models, may forget to load and use MCP tools or
fail to read MCP instructions).
:::
The hooks will:
- **`remind`**: Nudge the agent to use Serena's symbolic tools when it makes too many consecutive
`grep` or `read_file` calls without using any Serena tools in between.
- **`activate`**: Prompt the agent to activate the project and read Serena's instructions at session start.
- **`cleanup`**: Clean up hook session data when the session ends.
To set this up, create the file `~/.copilot/hooks/serena-hooks.json` with the following content:
```json
{
"hooks": {
"PreToolUse": [
{
"type": "command",
"command": "serena-hooks remind --client=vscode"
}
],
"SessionStart": [
{
"type": "command",
"command": "serena-hooks activate --client=vscode"
}
],
"Stop": [
{
"type": "command",
"command": "serena-hooks cleanup --client=vscode"
}
]
}
}
```
The `SessionStart` hook also addresses the global configuration limitation mentioned above — it will
automatically prompt the agent to activate the project directory, so you no longer need to do this manually.
## Codex (CLI and App)
You can simply run `serena setup codex`.
Alternatively, you can manually add the following to `~/.codex/config.toml` (create the file if it does not exist):
```toml
[mcp_servers.serena]
startup_timeout_sec = 25
command = "uvx"
args = ["-p", "3.13", "--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--project-from-cwd", "--context", "codex"]
startup_timeout_sec = 15
command = "serena"
args = ["start-mcp-server", "--project-from-cwd", "--context=codex"]
```
The larger startup timeout is to permit uvx to download the necessary dependencies. Once downloaded, the startup time is much faster.
:::{note}
The codex app does not start a session in the project's directory, so when using the app, you will have to
ask Codex to "Activate the current dir as project using serena" at the start of each session.
This is not necessary when using the codex CLI.
:::
:::{attention}
Codex currently ignores the [instructions](https://blog.modelcontextprotocol.io/posts/2025-11-03-using-server-instructions/)
property of MCP servers, so it is recommended to prompt the agent to
"read initial instructions for Serena" when starting your session, e.g. by mentioning this in your `AGENT.md`.
:::
**Verification.**
Run the `/mcp` command and verify that Serena is connected.
The Codex app does not start a session in the project's directory, so when using the app, we recommend
asking Codex to "Activate the current dir as project using serena" at the start of each session (though Codex might
do this automatically).
## Claude Desktop
@@ -197,14 +315,10 @@ Add the `serena` MCP server configuration
{
"mcpServers": {
"serena": {
"command": "uvx",
"command": "serena",
"args": [
"-p",
"3.13",
"--from",
"git+https://github.com/oraios/serena",
"serena",
"start-mcp-server"
"start-mcp-server",
"--context=claude-desktop"
]
}
}
@@ -214,6 +328,7 @@ Add the `serena` MCP server configuration
If your language server requires specific environment variables to be set (e.g. F# on macOS with Homebrew),
you can add them via an `env` key (see [above](#clients-common-pitfalls)).
**Verification.**
Once you have created the new MCP server entry, save the config and then restart Claude Desktop.
:::{attention}
@@ -223,28 +338,49 @@ minimize it.
After restarting, you should see Serena's tools in your chat interface (notice the small hammer icon).
For more information on MCP servers with Claude Desktop,
see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user).
## Copilot CLI
## JetBrains Junie
In the interactive mode, you can call `/mcp add` from within the copilot CLI. There, use serena as name,
STDIO as the server type, and `serena start-mcp-server --context=copilot-cli --project-from-cwd` as command.
Open Junie, go to the three dots in the top right corner, then Settings / MCP Settings and add Serena to Junie's global
MCP server configuration:
Alternatively, add the following to `~/.copilot/mcp-config.json` (create the file if it does not exist):
```json
{
"mcpServers": {
"serena": {
"command": "uvx",
"type": "stdio",
"command": "serena",
"tools": [
"*"
],
"args": [
"-p",
"3.13",
"--from",
"git+https://github.com/oraios/serena",
"serena",
"start-mcp-server",
"--context",
"ide"
"--context=copilot-cli",
"--project-from-cwd"
]
}
}
}
```
**Verification.**
Copilot should now show that Serena is running, though you may have to restart it.
## JetBrains Junie
For the Junie plugin in JetBrains IDEs, go to the three dots in the top right corner,
then Settings / MCP Settings and add Serena to Junie's global MCP server configuration:
```json
{
"mcpServers": {
"serena": {
"command": "serena",
"args": [
"start-mcp-server",
"--context=junie"
]
}
}
@@ -254,6 +390,23 @@ MCP server configuration:
You will have to prompt Junie to "Activate the current project using serena's activation tool" at the
start of each session.
For Junie CLI, where the project can be activated automatically on startup, edit `~/.junie/mcp/mcp.json` and add
```json
{
"mcpServers": {
"serena": {
"command": "serena",
"args": [
"start-mcp-server",
"--context=junie",
"--project-from-cwd"
]
}
}
}
```
## JetBrains AI Assistant
Here you can set up the more convenient per-project MCP server configuration, as the AI assistant supports specifying
@@ -265,16 +418,10 @@ Go to Settings / Tools / AI Assistant / MCP and add a new **local** configuratio
{
"mcpServers": {
"serena": {
"command": "uvx",
"command": "serena",
"args": [
"-p",
"3.13",
"--from",
"git+https://github.com/oraios/serena",
"serena",
"start-mcp-server",
"--context",
"ide",
"--context=jb-ai-assistant",
"--project",
"$(pwd)"
]
@@ -293,16 +440,10 @@ Add this configuration:
{
"mcpServers": {
"serena": {
"command": "uvx",
"command": "serena",
"args": [
"-p",
"3.13",
"--from",
"git+https://github.com/oraios/serena",
"serena",
"start-mcp-server",
"--context",
"ide"
"--context=antigravity"
]
}
}
@@ -340,7 +481,7 @@ in order to reduce tool duplication.
Most of the popular existing coding assistants (e.g. IDE extensions) and AI-enabled IDEs themselves support connections
to MCP Servers. Serena generally boosts performance by providing efficient tools for symbolic operations.
We generally recommend to use the `ide` context for these integrations by adding the arguments `--context ide`
We generally recommend using the `ide` context for these integrations by adding the arguments `--context ide`
in order to reduce tool duplication.
### Local GUIs and Agent Frameworks
@@ -354,5 +495,5 @@ Some of the leading open source GUI applications are
* [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp) and
* [Agno](https://docs.agno.com/introduction/playground).
These applications allow to combine Serena with almost any LLM (including locally running ones)
These applications allow combining Serena with almost any LLM (including locally running ones)
and offer various other integrations.
src/serena/resources/config/contexts/antigravity.yml
+26
View File
@@ -0,0 +1,26 @@
description: Generic IDE coding agent context (basic file operations and shell operations assumed to be covered; single project mode)
prompt: |
You are running in an IDE assistant context where file operations, basic (line-based) edits and reads,
and shell commands are handled by your own, internal tools.
If Serena's tools can be used to achieve your task, you should prioritize them.
In particular, it is important that you avoid reading entire source code files unless it is strictly necessary!
Instead, for exploring and reading code in a token-efficient manner, use Serena's overview and symbolic search tools.
For non-code files or for reads where you don't know the symbol's name path, you can use the pattern search tool.
excluded_tools:
- create_text_file
- read_file
- execute_shell_command
- find_file
- list_dir
tool_description_overrides: {}
# whether to assume that Serena shall only work on a single project in this context (provided that a project is given
# when Serena is started).
# If set to true and a project is provided at startup, the set of tools is limited to those required by the project's
# concrete configuration, and other tools are excluded completely, allowing the set of tools to be minimal.
# Tools explicitly disabled by the project will not be available at all.
# The `activate_project` tool is always disabled in this case, as project switching cannot be allowed.
single_project: true
src/serena/resources/config/contexts/claude-code.yml
+2
View File
@@ -13,6 +13,8 @@ excluded_tools:
- read_file
- execute_shell_command
- replace_content
- find_file
- list_dir
tool_description_overrides: {}
src/serena/resources/config/contexts/codex.yml
+2
View File
@@ -14,6 +14,8 @@ excluded_tools:
- read_file
- execute_shell_command
- replace_content
- find_file
- list_dir
tool_description_overrides: {}
src/serena/resources/config/contexts/copilot-cli.yml
+25
View File
@@ -0,0 +1,25 @@
description: Claude Code (CLI agent where file operations, basic edits, etc. are already covered; single project mode)
prompt: |
You are running in a CLI coding agent context where file operations, basic (line-based) edits and reads
as well as shell commands are handled by your own, internal tools.
If Serena's tools can be used to achieve your task, you should prioritize them.
In particular, it is important that you avoid reading entire source code files unless it is strictly necessary!
Instead, for exploring and reading code in a token-efficient manner, use Serena's overview and symbolic search tools.
For non-code files or for reads where you don't know the symbol's name path, you can use the pattern search tool.
excluded_tools:
- create_text_file
- read_file
- execute_shell_command
- replace_content
tool_description_overrides: {}
# whether to assume that Serena shall only work on a single project in this context (provided that a project is given
# when Serena is started).
# If set to true and a project is provided at startup, the set of tools is limited to those required by the project's
# concrete configuration, and other tools are excluded completely, allowing the set of tools to be minimal.
# Tools explicitly disabled by the project will not be available at all.
# The `activate_project` tool is always disabled in this case, as project switching cannot be allowed.
single_project: true
src/serena/resources/config/contexts/ide.yml
+2
View File
@@ -12,6 +12,8 @@ excluded_tools:
- create_text_file
- read_file
- execute_shell_command
- find_file
- list_dir
tool_description_overrides: {}
src/serena/resources/config/contexts/jb-ai-assistant.yml
+26
View File
@@ -0,0 +1,26 @@
description: Generic IDE coding agent context (basic file operations and shell operations assumed to be covered; single project mode)
prompt: |
You are running in an IDE assistant context where file operations, basic (line-based) edits and reads,
and shell commands are handled by your own, internal tools.
If Serena's tools can be used to achieve your task, you should prioritize them.
In particular, it is important that you avoid reading entire source code files unless it is strictly necessary!
Instead, for exploring and reading code in a token-efficient manner, use Serena's overview and symbolic search tools.
For non-code files or for reads where you don't know the symbol's name path, you can use the pattern search tool.
excluded_tools:
- create_text_file
- read_file
- execute_shell_command
- find_file
- list_dir
tool_description_overrides: {}
# whether to assume that Serena shall only work on a single project in this context (provided that a project is given
# when Serena is started).
# If set to true and a project is provided at startup, the set of tools is limited to those required by the project's
# concrete configuration, and other tools are excluded completely, allowing the set of tools to be minimal.
# Tools explicitly disabled by the project will not be available at all.
# The `activate_project` tool is always disabled in this case, as project switching cannot be allowed.
single_project: true
src/serena/resources/config/contexts/junie.yml
+24
View File
@@ -0,0 +1,24 @@
description: Generic IDE coding agent context (basic file operations and shell operations assumed to be covered; single project mode)
prompt: |
You are running in an IDE assistant context where file operations, basic (line-based) edits and reads,
and shell commands are handled by your own, internal tools.
If Serena's tools can be used to achieve your task, you should prioritize them.
In particular, it is important that you avoid reading entire source code files unless it is strictly necessary!
Instead, for exploring and reading code in a token-efficient manner, use Serena's overview and symbolic search tools.
For non-code files or for reads where you don't know the symbol's name path, you can use the pattern search tool.
excluded_tools:
- create_text_file
- read_file
- execute_shell_command
tool_description_overrides: {}
# whether to assume that Serena shall only work on a single project in this context (provided that a project is given
# when Serena is started).
# If set to true and a project is provided at startup, the set of tools is limited to those required by the project's
# concrete configuration, and other tools are excluded completely, allowing the set of tools to be minimal.
# Tools explicitly disabled by the project will not be available at all.
# The `activate_project` tool is always disabled in this case, as project switching cannot be allowed.
single_project: true
src/serena/resources/config/contexts/vscode.yml
+29
View File
@@ -0,0 +1,29 @@
description: Generic IDE coding agent context (basic file operations and shell operations assumed to be covered; single project mode)
prompt: |
In addition to Serena's tools, you have access to internal tools, including for, basic (line-based) edits and reads,
and shell commands.
If Serena's tools can be used to achieve your task, you should prioritize them.
In particular, it is important that you avoid reading entire source code files unless it is strictly necessary!
Instead, for exploring and reading code in a token-efficient manner, use Serena's overview and symbolic search tools.
For non-code files or for reads where you don't know the symbol's name path, you can use the pattern search tool.
Make sure to first activate the working directory as using Serena's `activate_project` tool and to read initial
instructions (if not done so already) with the `initial_instructions` tool.
excluded_tools:
- create_text_file
- read_file
- execute_shell_command
- find_file
- list_dir
tool_description_overrides: {}
# whether to assume that Serena shall only work on a single project in this context (provided that a project is given
# when Serena is started).
# If set to true and a project is provided at startup, the set of tools is limited to those required by the project's
# concrete configuration, and other tools are excluded completely, allowing the set of tools to be minimal.
# Tools explicitly disabled by the project will not be available at all.
# The `activate_project` tool is always disabled in this case, as project switching cannot be allowed.
single_project: true