Amethyst MCP

Amethyst MCPは、AIクライアントからModel Context Protocolを通じてAmethystのツールを利用するための仕組みです。

Amethyst MCPは、Amethystを契約しているユーザー向けに提供しています。一般公開のダウンロードではありません。

できること

Amethyst MCPを接続すると、AIクライアントから利用可能なワークスペースの確認、プロジェクト一覧の取得、対応済みのSearch Analytics、User Analytics、Index Worker操作などを実行できます。

事前準備

Amethyst MCPの実行にはNode.js 20以降が必要です。Node.jsをインストールしていない場合は、Node.js公式ダウンロードページ から先にインストールしてください。

Amethyst MCPをダウンロードする

Amethyst MCPをダウンロードする

上記リンクから amethyst-mcp.tar.gz をダウンロードしてください。

ダウンロード後、利用するターミナルに合わせた手順でファイルを展開します。

macOS / Linux

tar -xzf amethyst-mcp.tar.gz
cd amethyst-mcp
ls -l dist/index.js

Windows (PowerShell)

tar -xzf .\amethyst-mcp.tar.gz
Set-Location .\amethyst-mcp
Get-Item .\dist\index.js

Windows (Command Prompt)

tar -xzf amethyst-mcp.tar.gz
cd amethyst-mcp
dir dist\index.js

配布物は依存関係を含めてバンドル済みで、Node.jsが利用できる環境であればOSごとに別のファイルを選ぶ必要はありません。展開後に npm install や pnpm install を実行する必要はありません。

パスを確認する

MCPクライアントには、Node.jsの絶対パスと、展開した dist/index.js の絶対パスを設定します。利用するターミナルのタブを選んで確認してください。

macOS / Linux

Node.jsのパスを確認します。

which node

展開したディレクトリで、Amethyst MCPのentrypointを確認します。

echo "$(pwd)/dist/index.js"

Windows (PowerShell)

Node.jsのパスを確認します。

(Get-Command node).Source

展開したディレクトリで、Amethyst MCPのentrypointを確認します。

(Resolve-Path .\dist\index.js).Path

Windows (Command Prompt)

Node.jsのパスを確認します。

where node

展開したディレクトリで、Amethyst MCPのentrypointを確認します。

for %I in (dist\index.js) do @echo %~fI

表示された絶対パスを、次の設定で使います。

MCPクライアントに設定する

設定方法は利用するMCPクライアントによって異なります。具体的な設定場所や反映方法は、利用中のクライアントの公式ドキュメントを確認してください。

• Claude Desktop: Local MCP servers
• Claude Code: MCP
• Cursor: Model Context Protocol
• MCP client examples

Amethyst MCPをlocal stdio serverとして追加する際は、次の値を使います。

{
  "mcpServers": {
    "amethyst": {
      "command": "<absolute-path-to-node>",
      "args": ["<absolute-path-to-amethyst-mcp>/dist/index.js"],
      "env": {
        "AMETHYST_GRAPHQL_ENDPOINT": "https://api.amethy.st/query",
        "AMETHYST_FRONTEND_URL": "https://app.amethy.st"
      }
    }
  }
}

AMETHYST_GRAPHQL_ENDPOINT を省略した場合、Amethyst MCP は https://api.amethy.st/query を使用します。設定内容を確認しやすくするため、明示しておくことをおすすめします。

Codexに設定する場合

Codexでは、~/.codex/config.toml に次の設定を追加します。既存の [mcp_servers.*] がある場合は消さずに、amethyst のブロックだけ追加してください。

[mcp_servers.amethyst]
command = "<absolute-path-to-node>"
args = ["<absolute-path-to-amethyst-mcp>/dist/index.js"]

  [mcp_servers.amethyst.env]
  AMETHYST_GRAPHQL_ENDPOINT = "https://api.amethy.st/query"
  AMETHYST_FRONTEND_URL = "https://app.amethy.st"

MCP client機能を有効化していないCodex環境では、同じ config.toml に次の設定も追加してください。既に [features] がある場合は、その中に rmcp_client = true を追加します。

[features]
rmcp_client = true

設定を変更したらCodexを再起動してください。

MCPクライアントを再起動する

設定を変更したら、MCPクライアントを完全に終了してから再起動します。多くのクライアントでは、MCPサーバー設定はアプリ起動時に読み込まれます。

OAuth認可を完了する

再起動後、MCPクライアントでAmethystのツールを使うように依頼します。

アクセスできるAmethystのワークスペースを一覧して

初回のツール呼び出し時は、次の流れになります。

1. ブラウザでAmethystが開く
2. 必要に応じてAmethystにログインする
3. 許可するワークスペースを選ぶ
4. Approveする
5. 一時的なlocalhost callbackページに戻る

認可が完了したらMCPクライアントに戻ります。自動で完了しない場合は、同じ依頼をもう一度実行してください。

認可をやり直す

再認可したい場合は、保存済みcredentialを削除してMCPクライアントを再起動します。

• macOS / Linux: ~/.config/amethyst-mcp/oauth-token.json
• Windows: %APPDATA%\amethyst-mcp\oauth-token.json

次回のAmethystツール呼び出し時に、OAuth認可が再度始まります。

トラブルシュート

• MCPクライアントがサーバーを起動できない場合は、command と args の絶対パスを確認してください。
• ブラウザが開かない場合は、MCPクライアントのエラー出力に表示される認可URLを手動で開いてください。
• 401 または 403 エラーが出る場合は、保存済みcredentialを削除し、MCPクライアントを再起動して再認可してください。
• ダウンロードリンクを開けない場合は、Amethystサポートにお問い合わせください。