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