Amazon Q Developer CLI で MCPサーバーを設定する際のハマりポイント（2025/05/02）

はじめに

こんにちは。NCDC株式会社ITコンサルタントの藏原です。
MCPによって、いよいよ生成AIのビジネス利用範囲が広がってきましたね。

Amazon Q Developer CLIが、v1.9.0からMCPサーバーを使えるようになりました。
そこで、MCPサーバーを設定する際に遭遇した問題と解決策について共有します。この記事は2025年5月2日時点の情報に基づいています。

前提条件

• AWS Builderアカウントが必要です
• AWSのホームページ を参考に、Homebrewを使用してインストールを行います

$ brew install amazon-q

主な課題と解決策

1. パスの問題

最初に遭遇する可能性が高い問題は、パスが正しく通っていない状況です。

$ q --version
zsh: command not found:

解決策：Amazon QのデスクトップアプリケーションからIntegrationを設定することで解決できます。

2. MCPサーバーが追加できないの問題

現在、amazon Q cliに「MCPサーバーを追加したい」とお願いすると、以下のようなコマンドを案内されます。これは現在失敗します

$ q mcp add github
error: unrecognized subcommand 'mcp'
Usage: q [OPTIONS] [COMMAND]
For more information, try '--help'.
This command may be valid in newer versions of the Amazon Q CLI. Try running q update.

将来的にはこのようなサブコマンドでmcpを設定できるようになるのかもしれませんが、今はできないですね。
というわけで、ClaudeやClineのように、jsonファイルでMCPサーバーを追加していきます。

しかし、ここでも問題があります。
amazon-qをbrew経由でインストールすると、ホームディレクトリに以下のディレクトリが存在すると思います。

- ~/.aws ## AWS CLIを設定した時にできたディレクトリ
  - ~/.aws/amazonq
- ~/.amazon-q ## 今回できたディレクトリ

設定ファイルはどこに配置すればいいのか？
解決策: ~/.aws/amazonq ディレクトリの下にmcp.jsonファイルを作成します
AWSの公式HPにもありますが、正解は~/.aws/amazonq/の下になります。
公式HPの通り、下記フォーマットで追加したいMCPサーバーを記述します。

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://USERNAME:PASSWORD@HOST:5432/DBNAME"
      ]
    }
  }
}

設定したのち、qを再起動します（bashの再起動は不要）
MCPの設定に成功すると、qの起動時にMCPサーバーが正しくload, initializeされることがわかります。

おめでとうございます！　これで初期設定のハマりポイントを潜り抜けて、amazon Q Developer CLIでMCPサーバーを使う準備が整いました。

現状の疑問点

• 以下のサーバーはデフォルトで入っているようですが、設定ファイルはどこにあるんですかね…
  • filesystem
  • execute_bash
  • use_aws
  • report_issue

既知の課題

• 他のmcpサーバーの設定をgithubからqに引っ張ってきて欲しかったのですが、うまくいかないようです。無限curlする…
  • みのるんさんが指摘しているこれでしょうかね…？
• 上記の問題に加えて、brave-searchでWeb検索が失敗した際にもおきましたが、一度実行に失敗すると、execute_bashが無限に試されるようです。
  この問題については継続して調査中です。

これらの情報が、同様の設定を行う方々の助けになれば幸いです。