mirror of
https://github.com/tiennm99/serena.git
synced 2026-10-13 20:15:20 +00:00
Enhanced documentation on connecting to clients
This commit is contained in:
Michael Panchenko authored and Dominik Jain committed
1 parent
c35f0fa5b5
commit
f07db2550b
1 file changed
+174
-65
+174
-65
@@ -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 <path>` 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 -- <serena> start-mcp-server --context claude-code --project "$(pwd)"
|
||||
```
|
||||
|
||||
where `<serena>` 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
|
||||
`<your_project>/.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
|
||||
|
||||
|
||||
Reference in new issue
Block a user