💧
aqua でインストールしたツールが MCP Server で実行できない場合の解決方法

2025/06/08に公開
Model Context Protocol
本記事では MCP Server および MCP Server が実行するコマンドを CLI Version Manager の aqua でインストールし、 Cline で実行しようとしたところ、それらの実行に失敗してしまった件の原因と解決策を紹介します。
なお、自分は LLM や MCP Server にはあまり詳しくないので不正確なことを書くかもしれませんが、その場合は優しく指摘してもらえると助かります。

また今回取り上げる MCP Server とその MCP Server が実行するコマンドの詳細は伏せておきます。

記事中の MCP Server やコマンド名は実際のものとは異なります。

なお、今回の問題は aqua に限った話ではなく、 asdf や *env のようなバージョンマネージャー全般で起こりうる問題なはずです。

今回の問題は Cline で起こりましたが、 Cline 以外でどうかは分かりません。

 要約aqua の問題ではない
Cline は PATH 環境変数を引き継がないので、 AQUA_GLOBAL_CONFIG を cline_mcp_settings.json で明示的に設定した方が良い
https://github.com/cline/cline/issues/3533

Cline は MCP Server をルートディレクトリで実行するっぽい
MCP Server を aqua でインストールする場合は AQUA_GLOBAL_CONFIG を使って global にインストールするのが良い
MCP Server 上でコマンドを実行する場合は実行ディレクトリを明示的に指定しないと aqua.yaml が無視されて思わぬ結果になるかも

ある CLI ツールを実行する MCP Server を開発していた知人から、そのツールを aqua でインストールすると MCP 経由でツールが実行できないという相談を受けました。

相談を受けて、まずはその MCP Server のバイナリを aqua でインストールし、 Cline から実行するためにcline_mcp_settings.json を設定しました。
cline_mcp_settings.json
{
  "mcpServers": {
    "hello-mcp-server-foo": {
      "command": "hello-mcp-server",
      "args": [
        "foo"
      ],
      "transportType": "stdio",
      "disabled": false,
      "autoApprove": []
    }
  }
}
すると MCP Server の起動に失敗しました。
time="2025-05-30T22:22:37+09:00" level=fatal msg="aqua failed" aqua_version=2.51.2 doc="https://aquaproj.github.io/docs/reference/codes/004" env=darwin/arm64 error="command is not found" exe_name=hello-mcp-server program=aqua MCP error -32000: Connection closed
aqua を使ってインストールしたはずの hello-mcp-server がないと怒られています。

ただし、 terminal では hello-mcp-server を実行できました。

aqua のエラーログが出ていることから $(aqua root-dir)/bin に symbolic link は作られていてかつ $PATH は通っているようですが、 (aqua-proxy ではなく) aqua が hello-mcp-server をみつけられていません。

hello-mcp-server は Go で実装されていたので、ビルドして ~/go/bin 配下にインストールしてその絶対パスを指定すると hello-mcp-server は実行できました。
      "command": "/home/suzuki-shunsuke/go/bin/hello-mcp-server",
すると今度は hello-mcp-server が aqua でインストールしたコマンド foo を実行するのに失敗していました。
Error: failed to check foo command: exit status 1 MCP error -32000: Connection closed
これが元々相談されていたエラーです。

terminal 上では問題なく foo は実行できました。
一旦 aqua でインストールした hello-mcp-server が実行できない問題はおいといて、 foo が実行できない原因を調べました。

問題の MCP Server のコードを見ると https://github.com/mark3labs/mcp-go を使っていて、

server.NewMCPServer で MCPServer を生成する前に foo version コマンドを実行して foo コマンドがインストールされているかチェックしていました。

そのチェックで foo version コマンドが失敗して上記のエラーを吐いていました。

 Cline は MCP Server をルートディレクトリで実行するっぽいfoo コマンドは 2 つの aqua.yaml でインストールされていました。
カレントディレクトリ (hello-mcp-server のリポジトリ直下)
AQUA_GLOBAL_CONFIG
カレントディレクトリにある aqua.yaml が無視されるということは、 foo version がカレントディレクトリで実行されていないのではないかと思い、実行ディレクトリをデバッグで出力してみたところ、 root directory で実行されているようでした。

つまり Cline が MCP Server をルートディレクトリで実行しているのかなと思います (Cline のドキュメントをちゃんと調べたりしてませんが、そう見えます)。
aqua や asdf のようなバージョンマネージャーでツールを管理する場合、ツールのバージョンは実行ディレクトリに依存します。

そのため、先述のように MCPServer を生成する前にコマンドがインストールされているかをチェックすることは原理上できません。

そこで MCPServer を生成する前にコマンドがインストールされているかチェックするコードを消すことで元々の問題を解決できました。

元々このチェックはインストールされていない場合に早めにエラーを返すためにされていただけなので、消しても大きな問題はありませんでした。

 Cline では PATH 以外の環境変数が引き継がれないまた、ルートディレクトリで実行していてカレントディレクトリの aqua.yaml が無視されている場合であっても、本来 AQUA_GLOBAL_CONFIG が参照されるはずですが、されませんでした。

これは foo version コマンド実行時に AQUA_GLOBAL_CONFIG が渡ってないのではないかと思い、

cline_mcp_settings.json で AQUA_GLOBAL_CONFIG を設定すると解決しました。
"env": {
  "AQUA_GLOBAL_CONFIG": "/home/suzuki-shunsuke/repos/src/github.com/aquaproj/aqua-registry/aqua-all.yaml"
},
先述の MCP Server hello-mcp-server が実行できない問題もこれで解決しました。

これについては issue がありました。
https://github.com/cline/cline/issues/3533
修正 PR もありましたが、おそらく Security 上の理由で意図的に環境変数を渡してないのだと思うので、この修正が取り込まれる可能性は低いのではないかと思います。
https://github.com/cline/cline/pull/3578

 最後にaqua でインストールしたツールが Cline, MCP Server 経由で実行できない問題を調べました。

ターミナル上で実行できるのに Cline, MCP Server 経由で実行できない場合は、環境変数 (PATH, AQUA_GLOBAL_CONFIG) やコマンドを実行しているディレクトリがどこかを確認すると良いかと思います。
要約

Cline は MCP Server をルートディレクトリで実行するっぽい

Cline では PATH 以外の環境変数が引き継がれない

最後に

Discussion
