From f07db2550bdfe991099aa2678f03b4d6a762ad62 Mon Sep 17 00:00:00 2001 From: Michael Panchenko Date: Fri, 12 Dec 2025 17:31:34 +0700 Subject: [PATCH 1/2] Enhanced documentation on connecting to clients --- docs/02-usage/030_clients.md | 239 +++++++++++++++++++++++++---------- 1 file changed, 174 insertions(+), 65 deletions(-) diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index 57b69151..7e6e1a3f 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -6,19 +6,58 @@ Depending on your needs, you might want to customize Serena's behaviour by * [adding command-line arguments](mcp-args) * [adjusting configuration](050_configuration). +While you may be able to turn off tools through your client's interface (e.g., in VSCode or Claude Desktop), +we **highly** recommend selecting your toolset through the +Serena configuration instead, since Serena's prompts automatically +adjust based on which tools are enabled/disabled. + +## General + +> Please make sure to read these general instructions before proceeding to the client-specific sections below! + +In the section on [running the MCP server](020_running), we described various ways of starting the Serena server. For +brevity, here we present only commands that use the `uvx` way and the `stdio` protocol. You can easily adapt the +commands to your preferred way of running Serena. + +Some clients have a per-workspace MCP configuration (e.g., VSCode and Claude Code), while others have a global MCP +configuration (e.g., Codex and Claude Desktop). + +- In the per-workspace case, you typically want Serena to start + within the project directory and never switch to a different project, which is achieved by specifying the + `--project ` argument when starting the MCP server. This also disables the `activate_project` tool. +- In the global configuration case, you must first activate the project you want to work on, which you can do by asking + the LLM to do so (e.g., "Activate the current dir as project using serena"). In such settings, the `activate_project` + tool is required. + +### Common Pitfalls + +Your client may not escape backslashes on Windows (e.g., Claude Desktop does not). +If you are using paths containing backslashes for paths on Windows +(note that you can also just use forward slashes), be sure to escape them correctly (`\\`). + +Your client may not find the `uvx` command, even if it is on your system PATH. +In this case, you should provide the full path to the `uvx` executable. + +Some language servers may require additional environment variables to be set (e.g. F# on macOS with Homebrew), +which you may need to explicitly add to the MCP server configuration. +Note that for some clients (including Claude Desktop), the spawned processes may not inherit environment variables that +are only configured in your shell +profile (e.g. `.bashrc`, `.zshrc`, etc.); they would need to be set system-wide instead. +An easy fix is to add them explicitly to the MCP server entry: many clients allow adding an `env` key to the `serena` +object, e.g. + +``` +"env": { + "DOTNET_ROOT": "/opt/homebrew/Cellar/dotnet/9.0.8/libexec" +} +``` + ## Claude Code Serena is a great way to make Claude Code both cheaper and more powerful! From your project directory, add serena with a command like this, -```shell -claude mcp add serena -- start-mcp-server --context claude-code --project "$(pwd)" -``` - -where `` is [your way of running Serena](020_running). -For example, when using `uvx`, the above command becomes - ```shell claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)" ``` @@ -29,8 +68,35 @@ Note: * 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. - -Be sure to use at least `v1.0.52` of Claude Code (as earlier versions do not read MCP server system prompts upon startup). + + +## VSCode + +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 +`/.vscode/mcp.json`, or edit the entry after using the option `install into workspace`: + +```json +{ + "servers": { + "oraios/serena": { + "type": "stdio", + "command": "uvx", + "args": [ + "--from", + "git+https://github.com/oraios/serena", + "serena", + "start-mcp-server", + "--context", + "ide", + "--project", + "${workspaceFolder}" + ] + } + }, + "inputs": [] +} +``` ## Codex @@ -45,6 +111,7 @@ For example, when using `uvx`, add the following section: command = "uvx" args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"] ``` + After codex has started, you need to activate the project, which you can do by saying: "Activate the current dir as project using serena" @@ -67,73 +134,115 @@ community version](https://github.com/aaddrick/claude-desktop-debian). To configure MCP server settings, go to File / Settings / Developer / MCP Servers / Edit Config, which will let you open the JSON file `claude_desktop_config.json`. -Add the `serena` MCP server configuration, using a [run command](020_running.md) depending on your setup. +Add the `serena` MCP server configuration -* local installation: - - ```json - { - "mcpServers": { - "serena": { - "command": "/abs/path/to/uv", - "args": ["run", "--directory", "/abs/path/to/serena", "serena", "start-mcp-server"] - } - } - } - ``` - -* uvx: - - ```json - { - "mcpServers": { - "serena": { - "command": "/abs/path/to/uvx", - "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"] - } - } +```json +{ + "mcpServers": { + "serena": { + "command": "uvx", + "args": [ + "--from", + "git+https://github.com/oraios/serena", + "serena", + "start-mcp-server" + ] + } } - ``` - -* docker: - - ```json - { - "mcpServers": { - "serena": { - "command": "docker", - "args": ["run", "--rm", "-i", "--network", "host", "-v", "/path/to/your/projects:/workspaces/projects", "ghcr.io/oraios/serena:latest", "serena", "start-mcp-server", "--transport", "stdio"] - } - } - } - ``` - -If you are using paths containing backslashes for paths on Windows -(note that you can also just use forward slashes), be sure to escape them correctly (`\\`). - -:::{note} -Some language servers may require additional environment variables to be set (e.g. F# on macOS with Homebrew), -which you may need to explicitly add to the MCP server configuration. -Note that the spawned processes will not inherit environment variables that are only configured in your shell -profile (e.g. `.bashrc`, `.zshrc`, etc.); they would need to be set system-wide instead. -An easy fix is to add them explicitly to the MCP server entry: Simply add an `env` key to the `serena` object, e.g. - -``` -"env": { - "DOTNET_ROOT": "/opt/homebrew/Cellar/dotnet/9.0.8/libexec" } ``` -::: -Once you have created the new MCP server entry, save the config and then restart Claude Desktop. +Once you have created the new MCP server entry, save the config and then restart Claude Desktop. :::{attention} -Be sure to fully quit the Claude Desktop application via File / Exit, as regularly closing the application will just minimize it. +Be sure to fully quit the Claude Desktop application via File / Exit, as regularly closing the application will just +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). +For more information on MCP servers with Claude Desktop, +see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). + +## JetBrains Junie + +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: + +```json +{ + "mcpServers": { + "serena": { + "command": "uvx", + "args": [ + "--from", + "git+https://github.com/oraios/serena", + "serena", + "start-mcp-server", + "--context", + "ide" + ] + } + } +} +``` + +You will have to prompt Junie to "Activate the current project using serena's activation tool" at the +start of each session. + +## JetBrains AI Assistant + +Here you can set up the more convenient per-project MCP server configuration, as the AI assistant supports specifying +the launch working directory. + +Go to Settings / Tools / AI Assistant / MCP and add a new **local** configuration via the `as JSON` option: + +```json +{ + "mcpServers": { + "serena": { + "command": "uvx", + "args": [ + "--from", + "git+https://github.com/oraios/serena", + "serena", + "start-mcp-server", + "--context", + "ide", + "--project", + "$(pwd)" + ] + } + } +} +``` + +Then make sure to configure the working directory to be the project root. + +## Antigravity + +Add this configuration + +```json +{ + "mcpServers": { + "serena": { + "command": "uvx", + "args": [ + "--from", + "git+https://github.com/oraios/serena", + "serena", + "start-mcp-server", + "--context", + "ide" + ] + } + } +} +``` + +At the time of writing (12.2025), it does **not seem to work** due to schema validation issues in Antigravity. +The client starts Serena and then crashes with `[internal] marshal message: string field contains invalid UTF-8`. ## Other Clients From 0bbd1806bc88ccd8d87b2a1b75fdf58ca909da3a Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Mon, 15 Dec 2025 17:23:48 +0100 Subject: [PATCH 2/2] Refactor general instructions, restructure, minor improvements --- docs/02-usage/030_clients.md | 125 ++++++++++++++++++++--------------- 1 file changed, 73 insertions(+), 52 deletions(-) diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index 7e6e1a3f..74b84a00 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -1,49 +1,59 @@ # Connecting Your MCP Client -In the following, we provide default configurations for popular MCP-enabled clients. +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. -Depending on your needs, you might want to customize Serena's behaviour by - * [adding command-line arguments](mcp-args) - * [adjusting configuration](050_configuration). +(clients-general-instructions)= +## General Instructions -While you may be able to turn off tools through your client's interface (e.g., in VSCode or Claude Desktop), -we **highly** recommend selecting your toolset through the -Serena configuration instead, since Serena's prompts automatically -adjust based on which tools are enabled/disabled. +In general, Serena can be used with any MCP-enabled client. +To connect Serena to your favourite client, simply -## General +1. determine how to add a custom MCP server to your client (refer to the client's documentation). +2. add a new MCP server entry by specifying either + * a [run command](start-mcp-server) that allows the client to start the MCP server in stdio mode as a subprocess, or + * the URL of the HTTP/SSE endpoint, having started the [Serena MCP server in HTTP/SSE mode](streamable-http) beforehand. -> Please make sure to read these general instructions before proceeding to the client-specific sections below! +Depending on your needs, you might want to further customize Serena's behaviour by +* [adding command-line arguments](mcp-args) +* [adjusting configuration](050_configuration). -In the section on [running the MCP server](020_running), we described various ways of starting the Serena server. For -brevity, here we present only commands that use the `uvx` way and the `stdio` protocol. You can easily adapt the -commands to your preferred way of running Serena. +**Mode of Operation**. +Note that some clients have a per-workspace MCP configuration (e.g, VSCode and Claude Code), +while others have a global MCP configuration (e.g. Codex and Claude Desktop). -Some clients have a per-workspace MCP configuration (e.g., VSCode and Claude Code), while others have a global MCP -configuration (e.g., Codex and Claude Desktop). - -- In the per-workspace case, you typically want Serena to start - within the project directory and never switch to a different project, which is achieved by specifying the - `--project ` argument when starting the MCP server. This also disables the `activate_project` tool. +- In the per-workspace case, you typically want to start Serena with your workspace directory as the project directory + and never switch to a different project. This is achieved by specifying the + `--project ` argument with a single-project [context](#contexts) (e.g. `ide` or `claude-code`). - In the global configuration case, you must first activate the project you want to work on, which you can do by asking the LLM to do so (e.g., "Activate the current dir as project using serena"). In such settings, the `activate_project` tool is required. +**Tool Selection**. +While you may be able to turn off tools through your client's interface (e.g., in VSCode or Claude Desktop), +we recommend selecting your base tool set through Serena's configuration, as Serena's prompts automatically +adjust based on which tools are enabled/disabled. +A key mechanism for this is to use the appropriate [context](#contexts) when starting Serena. + +(clients-common-pitfalls)= ### Common Pitfalls -Your client may not escape backslashes on Windows (e.g., Claude Desktop does not). -If you are using paths containing backslashes for paths on Windows +**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, you should provide the full path to the `uvx` executable. +In this case, a workaround is to provide the full path to the `uvx` executable. +**Environment Variables**. Some language servers may require additional environment variables to be set (e.g. F# on macOS with Homebrew), which you may need to explicitly add to the MCP server configuration. -Note that for some clients (including Claude Desktop), the spawned processes may not inherit environment variables that -are only configured in your shell -profile (e.g. `.bashrc`, `.zshrc`, etc.); they would need to be set system-wide instead. -An easy fix is to add them explicitly to the MCP server entry: many clients allow adding an `env` key to the `serena` +Note that for some clients (e.g. Claude Desktop), the spawned MCP server process may not inherit environment variables that +are only configured in your shell profile (e.g. `.bashrc`, `.zshrc`, etc.); they would need to be set system-wide instead. +An easy fix is to add them explicitly to the MCP server entry. +For example, in Claude Desktop and other clients, you can simply add an `env` key to the `serena` object, e.g. ``` @@ -52,7 +62,16 @@ object, e.g. } ``` -## Claude Code +## Specific Clients + +:::{note} +In this section, we present example configurations that 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. +::: + +### Claude Code Serena is a great way to make Claude Code both cheaper and more powerful! @@ -70,7 +89,7 @@ Note: Claude Code's mode of operation. -## VSCode +### VSCode 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 @@ -98,7 +117,7 @@ While serena can be directly installed from the GitHub MCP server registry, we r } ``` -## Codex +### Codex Serena works with OpenAI's Codex CLI 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.). @@ -126,9 +145,9 @@ that was already taken). > Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected. -## Claude Desktop +### Claude Desktop -On Windows and macOS there are official [Claude Desktop applications by Anthropic](https://claude.ai/download), for Linux there is an [open-source +On Windows and macOS, there are official [Claude Desktop applications by Anthropic](https://claude.ai/download); for Linux, there is an [open-source community version](https://github.com/aaddrick/claude-desktop-debian). To configure MCP server settings, go to File / Settings / Developer / MCP Servers / Edit Config, @@ -152,6 +171,9 @@ 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)). + Once you have created the new MCP server entry, save the config and then restart Claude Desktop. :::{attention} @@ -164,7 +186,7 @@ After restarting, you should see Serena's tools in your chat interface (notice t For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). -## JetBrains Junie +### JetBrains Junie 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: @@ -190,7 +212,7 @@ 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. -## JetBrains AI Assistant +### JetBrains AI Assistant Here you can set up the more convenient per-project MCP server configuration, as the AI assistant supports specifying the launch working directory. @@ -219,9 +241,16 @@ Go to Settings / Tools / AI Assistant / MCP and add a new **local** configuratio Then make sure to configure the working directory to be the project root. -## Antigravity +### Antigravity -Add this configuration +:::{warning} +At the time of writing (12/2025), Antigravity does not seem to work with Serena due to schema validation issues +which are beyond our control. +The client starts Serena but then crashes with `[internal] marshal message: string field contains invalid UTF-8`. +Nevertheless, we provide a configuration that should work once the issue is resolved. +::: + +Add this configuration: ```json { @@ -241,22 +270,11 @@ Add this configuration } ``` -At the time of writing (12.2025), it does **not seem to work** due to schema validation issues in Antigravity. -The client starts Serena and then crashes with `[internal] marshal message: string field contains invalid UTF-8`. +### Other Clients -## Other Clients +For other clients, follow the [general instructions](#clients-general-instructions) above to set up Serena as an MCP server. -In general, Serena can be used with any MCP-enabled client. -To connect Serena to your favourite client, simply - -1. determine how to add a custom MCP server to your client (refer to the client's documentation). -2. add a new MCP server entry by specifying either - * a [run command](start-mcp-server) that allows the client to start the MCP server in stdio mode as a subprocess, or - * the URL of the HTTP/SSE endpoint, having started the [Serena MCP server in HTTP/SSE mode](streamable-http) beforehand. - -Below, we list some popular categories of clients that Serena can be used with. - -### Terminal-Based Clients +#### Terminal-Based Clients There are many terminal-based coding assistants that support MCP servers, such as @@ -269,15 +287,18 @@ There are many terminal-based coding assistants that support MCP servers, such a They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena by writing your own context, modes or prompts to adjust it to the client's respective internal capabilities (and your general workflow). -### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) +In most cases, the `ide` context is likely to be appropriate for such clients, i.e. add the arguments `--context ide` +in order to reduce tool duplication. + +#### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) 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 to use the `ide` context for these integrations by adding the arguments `--context ide` in order to reduce tool duplication. -### Local GUIs and Agent Frameworks +#### Local GUIs and Agent Frameworks Over the last months, several technologies have emerged that allow you to run a local GUI client and connect it to an MCP server. The respective applications will typically work with Serena out of the box.