Serenaをバージョンを指定してインストールする＋Claude CodeのMCPサーバーとして登録する

これは、なにをしたくて書いたもの？

Serenaは便利なコーディングエージェントツールキットですが、インストール方法に以下のように書かれているのが
ちょっと気になります。

$ uvx --from git+https://github.com/oraios/serena serena 

これはSerenaのGitHubリポジトリーのmainブランチの最新コミットを使います。

uvxを試す - CLOVER🍀

いつ実行するかで結果が変わってしまうので、バージョンを固定する方法を見ておこうと思います。

この前提でClaude CodeのMCPサーバーとして登録する方法も見ておきましょうか。

環境

今回の環境はこちら。

$ uvx --version
uvx 0.9.15

Serenaのインストール方法

Serenaのインストール方法はこちらに記載があります。

Running Serena — Serena Documentation

uvxを使う方法、

$ uvx --from git+https://github.com/oraios/serena serena

GitHubリポジトリーからcloneしてきてローカルインストールする方法の2つですね。

$ git clone https://github.com/oraios/serena
$ cd serena


$ uv run serena

# または
$ uv run --directory /abs/path/to/serena serena

使う時にあまりコロコロとバージョンが変わって欲しくない時もあるので、固定する方法を考えてみましょう。

Serenaのバージョンを固定する

まずuvxで実行してみましょう。Serenaは--versionのようなオプションがないので、ヘルプで確認します…。

$ uvx --from git+https://github.com/oraios/serena serena --help
    Updated https://github.com/oraios/serena (2fa477397bf1af6526ff96fb867c3dab697a876b)
      Built serena-agent @ git+https://github.com/oraios/serena@2fa477397bf1af6526ff96fb867c3dab697a876b
Installed 58 packages in 45ms
Usage: serena [OPTIONS] COMMAND [ARGS]...

  Serena CLI commands. You can run `<command> --help` for more info on each
  command.

Options:
  --help  Show this message and exit.

Commands:
  config               Manage Serena configuration.
  context              Manage Serena contexts.
  mode                 Manage Serena modes.
  print-system-prompt  Print the system prompt for a project.
  project              Manage Serena projects.
  prompts              Commands related to Serena's prompts that are...
  start-mcp-server     Starts the Serena MCP server.
  tools                Commands related to Serena's tools.

2fa477397bf1af6526ff96fb867c3dab697a876bというコミットハッシュが見えますが、これはコマンド実行時のmainブランチの
最新コミットですね。

というわけで、実行時のバージョンを固定する方法を考えましょう。

1番簡単なのは、uvxで実行する時に@[バージョン]で指定することですね。

$ uvx --from git+https://github.com/oraios/serena@v0.1.4 serena --help
      Built serena-agent @ git+https://github.com/oraios/serena@d5f90710676b6a7cacc450f59005b4934c49b6db
Installed 55 packages in 45ms
Usage: serena [OPTIONS] COMMAND [ARGS]...

  Serena CLI commands. You can run `<command> --help` for more info on each
  command.

Options:
  --help  Show this message and exit.

Commands:
  config               Manage Serena configuration.
  context              Manage Serena contexts.
  mode                 Manage Serena modes.
  print-system-prompt  Print the system prompt for a project.
  project              Manage Serena projects.
  prompts              Commands related to Serena's prompts that are...
  start-mcp-server     Starts the Serena MCP server.
  tools                Commands related to Serena's tools.

これでもバージョンを固定できます。

ただ、これだと毎回GitHubへの通信が発生します。それが嫌な場合はローカルインストールですね。

$ git clone https://github.com/oraios/serena
$ cd serena

これで固定したいバージョンやコミットハッシュにチェックアウトしておくとよいでしょう。

$ git checkout v0.1.4

実行時には、ドキュメントにはSerenaのclone先をuv runの--directoryオプションで指定するように書かれています。

$ uv run --directory /path/to/serena serena [command]

ちなみに、初回はビルドを始めるので目的を考えると1度実行しておいた方がよいでしょう。

$ uv run --directory /path/to/serena serena --help
Using CPython 3.11.14
Creating virtual environment at: .venv
      Built serena-agent @ file://$HOME/serena
Installed 55 packages in 48ms
Usage: serena [OPTIONS] COMMAND [ARGS]...

  Serena CLI commands. You can run `<command> --help` for more info on each
  command.

Options:
  --help  Show this message and exit.

Commands:
  config               Manage Serena configuration.
  context              Manage Serena contexts.
  mode                 Manage Serena modes.
  print-system-prompt  Print the system prompt for a project.
  project              Manage Serena projects.
  prompts              Commands related to Serena's prompts that are...
  start-mcp-server     Starts the Serena MCP server.
  tools                Commands related to Serena's tools.

ところで、uv runの--directoryオプションは、そのディレクトリーに移動して実行することが書かれています。

Adding the --directory option results in the working directory being set to the Serena directory. As a consequence, you will need to specify paths when using CLI commands that would otherwise operate on the current directory.

確認してみましょう。

$ cd /tmp
$ uv run --directory /path/to/serena bash -c pwd
/path/to/serena

確かにそのようです。これが嫌な場合は、--projectを使った方がよいのでしょうか。

--projectでも--directoryで指定した時と同じように実行できます。

$ uv run --project /path/to/serena serena --help
Usage: serena [OPTIONS] COMMAND [ARGS]...

  Serena CLI commands. You can run `<command> --help` for more info on each
  command.

Options:
  --help  Show this message and exit.

Commands:
  config               Manage Serena configuration.
  context              Manage Serena contexts.
  mode                 Manage Serena modes.
  print-system-prompt  Print the system prompt for a project.
  project              Manage Serena projects.
  prompts              Commands related to Serena's prompts that are...
  start-mcp-server     Starts the Serena MCP server.
  tools                Commands related to Serena's tools.

--projectだとディレクトリーが移動しません。

$ cd /tmp
$ uv run --project /path/to/serena bash -c pwd
/tmp

Claude CodeのMCPサーバーとして登録する

SerenaをClaude CodeのMCPサーバーとして登録する方法は、こちらに書かれています。

Connecting Your MCP Client / Claude Code

コマンドとしてはこうですね。<serena>にはSerenaの実行方法が入ります。

$ claude mcp add serena -- <serena> start-mcp-server --context claude-code --project "$(pwd)"

uvxで簡単に使う場合はこうですね。

$ claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"

少し試しておきましょう。Claude Code＋Claude Code Router（Gemini）を使います。

$ claude --version
2.0.60 (Claude Code)


$ ccr version
claude-code-router version: 1.0.72

Claude Code RouterはGeminiを使うように設定。

$HOME/.claude-code-router/config.json

{
  "PORT": 3456,
  "Providers": [
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": "xxxxx",
      "models": ["gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-2.5-pro"],
      "transformer": {
        "use": ["gemini"]
      }
    }
  ],
  "Router": {
    "default": "gemini,gemini-2.5-flash",
    "think": "gemini,gemini-2.5-flash",
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

まずSerena MCPサーバーを登録。

$ claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"

よくよく考えると、この登録方法だと実行するタイミングでSerena MCPサーバーのバージョンが決まるということに
気づきますよね。

それはそれとして、Claude Codeを起動して

$ ccr code

確認。

> /status
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Settings:  Status   Config   Usage   (tab to cycle)

 Version: 2.0.60
 Session ID: a8c2f21e-0b9b-4d6a-95a8-1bf88d6bc1f0
 cwd: /path/to/project
 Auth token: ANTHROPIC_AUTH_TOKEN
 Anthropic base URL: http://127.0.0.1:3456

 Model: Default (claude-sonnet-4-5-20250929)
 MCP servers: serena ✔
 Memory:
 Setting sources: User settings, Shared project settings, Local, Command line arguments, Enterprise managed policies
 Esc to exit

よさそうです。

1度Serena MCPサーバーを削除。

$ claude mcp remove serena

今度はローカルにcloneしたSerenaを指定してみます。ここではv0.1.4のタグにチェックアウトしたものをそのまま使います。
またuv runのオプションは--project指定にしました。--projectオプションが2回出てきますが、2回目のものは
serena start-mcp-serverコマンドの--projectオプションですね。

$ claude mcp add serena -- uv run --project /path/to/serena serena start-mcp-server --context claude-code --project "$(pwd)"

そしてClaude Codeを起動して/statusを見ると…なんと起動に失敗しています。

> /status
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Settings:  Status   Config   Usage   (tab to cycle)

 Version: 2.0.60
 Session ID: 1384c267-ebf3-44eb-97ec-27aeea3cc368
 cwd: /path/to/project
 Auth token: ANTHROPIC_AUTH_TOKEN
 Anthropic base URL: http://127.0.0.1:3456

 Model: Default (claude-sonnet-4-5-20250929)
 MCP servers: serena ✘
 Memory:
 Setting sources: User settings, Shared project settings, Local, Command line arguments, Enterprise managed policies
 Esc to exit

単独でコマンドを実行して確認してみましょう。

$ uv run --project /path/to/serena serena start-mcp-server --context claude-code --project "$(pwd)"

なんと、--contextで指定したclaude-codeという値がわからないようです。

FileNotFoundError: Context claude-code not found in $HOME/.serena/contexts or in /path/to/serena/src/serena/resources/config/contexts.Available contexts:
['agent', 'chatgpt', 'codex', 'context.template', 'desktop-app', 'ide-assistant']

つまり、Serenaのドキュメントはmainブランチの内容になっていそうですね。

仕方がないので、1度削除して今度はide-assistantで登録し直しました。

$ claude mcp remove serena
$ claude mcp add serena -- uv run --project /path/to/serena serena start-mcp-server --context ide-assistant --project "$(pwd)"

今度は成功します。

> /status
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Settings:  Status   Config   Usage   (tab to cycle)

 Version: 2.0.60
 Session ID: 76ef4ee3-5a93-4757-bd17-eab84b89860e
 cwd: /path/to/project
 Auth token: ANTHROPIC_AUTH_TOKEN
 Anthropic base URL: http://127.0.0.1:3456

 Model: Default (claude-sonnet-4-5-20250929)
 MCP servers: serena ✔
 Memory:
 Setting sources: User settings, Shared project settings, Local, Command line arguments, Enterprise managed policies
 Esc to exit

実は最初は失敗しては、新しいSerenaを起動した後に古いSerenaを起動すると設定ファイルの互換性がなかったみたいです。

$ uv run --project /path/to/serena serena start-mcp-server --context ide-assistant --project "$(pwd)"

〜省略〜

  File "/path/to/serena/src/serena/config/serena_config.py", line 228, in _from_dict
    language_str = data["language"].lower()
                   ~~~~^^^^^^^^^^^^
KeyError: 'language'

この場合はSerenaの情報を1度削除しましょう。

$ rm -rf ~/.serena

こんな感じで、指定のSerena MCPサーバーを使えるようになるかなと思います。

オマケ

スコープをuserにして、どのプロジェクトで実行しても使えるようにするにはこんな感じでしょうか。

$ claude mcp add serena --scope user --env PROJECT_DIR='$PWD' -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project '$PROJECT_DIR'

おわりに

Serenaは便利なのですが、ドキュメントに習って素直に登録するとMCPサーバーとして起動するタイミングでバージョンが
変わりそうだなと思ったのでちょっと確認してみました。

普段は気にならないかもしれませんが、バージョンを固定したい時は覚えておいた方がよいかなと。