setup-mcp

Deepgram MCP サーバーをインストールする

ユーザー向けに Deepgram MCP 統合を設定します。以下の手順に従ってください。

ステップ 1：方法を選ぶ

方法は3つあります。ユーザーが Deepgram API キーを持っているか、または必要としているかに応じて選びます。

方法	サーバー	認証情報	インストール内容
A	Deepgram CLI MCP プロキシ（dg mcp）	Deepgram API キー 必須	CLI 全体（deepctl）
B	スタンドアロンの deepgram-mcp	Deepgram API キー 必須	Python パッケージ1つ
C	ホスト型 docs MCP（/_mcp/server）	不要	インストール不要

選択基準：

• ユーザーがすでに CLI を使っている、または dg listen / dg speak / dg init も使いたい → 方法 A。
• ユーザーは API キーを持っているが、CLI なしで MCP サーバーだけを使いたい → 方法 B。
• ユーザーが API キーを持っていない、または1つのコマンドですぐに使えるものを希望している → 方法 C。

方法 A/B には、キー認証が必要なホスト型のバリエーションもあります。インストールは不要です。下記の「kapa エンドポイントは認証情報なしでは利用できません」を参照してください。

方法 A と B は同じサーバーです。dg mcp は deepgram-mcp パッケージをラップします。どちらも Deepgram の開発者向け API をプロキシし、実行時に Deepgram からツール一覧を取得するため、パッケージをアップグレードしなくても、再接続時に新しいツールが表示されます。この記事の執筆時点では、一覧にあるのはドキュメントおよびナレッジソース検索ツール（search_deepgram_knowledge_sources）1つだけです。ツールセットを保証するのではなく、ユーザーのクライアントで tools/list を確認し、現在利用可能なものを調べてください。

方法 A/B と方法 C はどちらもドキュメントに基づいて Deepgram に関する質問に回答するため、複数をインストールするのは通常冗長です。認証情報なしで動作するのは方法 C だけです。

ステップ 2：環境を確認する

ユーザーが使用している AI コーディングツールを特定します。次を確認してください。

• Claude Code — プロジェクトまたはユーザーのホームディレクトリに .claude/ ディレクトリがあるか確認します
• Cursor — プロジェクトのルートに .cursor/ ディレクトリがあるか確認します
• Windsurf — プロジェクトのルートに .windsurf/ ディレクトリがあるか確認します

複数のツールが見つかった場合、または何も見つからなかった場合は、どのツールを設定するかユーザーに尋ねてください。

ステップ 3：適用範囲を確認する

MCP サーバーをどの範囲で設定するか、ユーザーに尋ねます。

• このプロジェクトのみ（チームのリポジトリにおすすめ）
• グローバル（すべてのプロジェクトで利用可能）

---

方法 A — Deepgram CLI MCP プロキシ（dg mcp）

A1. CLI をインストールする

まず dg --version（または deepctl --version、Windows では where dg）を確認します。パッケージ名は deepctl で、相互に置き換え可能な3つのバイナリ（dg、deepctl、deepgram）をインストールします。

# macOS / Linux — Homebrew (also brings in ffmpeg and portaudio)
brew install deepgram/tap/deepgram

# macOS / Linux — install script
curl -fsSL https://deepgram.com/install.sh | sh

# pip / uv / pipx
pip install deepctl
uv tool install deepctl
pipx install deepctl

# Windows — PowerShell
iwr https://deepgram.com/install.ps1 -useb | iex

アップグレードには、インストール時に使用した方法を使います：pip install -U deepctl、 uv tool upgrade deepctl、pipx upgrade deepctl、brew upgrade deepgram、またはインストール スクリプトを再実行してください。dg update --check-only は新しいリリースがあるかどうかを報告します。pip でインストールした場合、dg update を引数なしで実行するとアップグレードされず、代わりに installation_method: null が報告されます。

Homebrew では完全修飾名が重要です。Homebrew 6 は、信頼済みのサードパーティー製フォーミュラのみを読み込みます。brew install deepgram/tap/deepgram を実行するとそのフォーミュラが信頼済みになりますが、brew tap deepgram/tap && brew install deepgram は別途 brew trust を実行するまで失敗します。tap のフォーミュラは deepctl-0.2.26 を固定していますが、pip、uv、pipx では 0.3.1 がインストールされます。

A2. 認証する — 必須

認証情報がないと dg mcp は起動しません。エディターを設定する前に実行してください。

dg login                  # interactive; or dg login --api-key <KEY>
dg whoami                 # confirm: "authenticated": true

環境変数の DEEPGRAM_API_KEY を使う場合は、dg login は不要です。キーは https://console.deepgram.com で取得できます。

A3. エディターを設定する

Claude Code

# Project scope
claude mcp add deepgram --scope project dg mcp

# User/global scope
claude mcp add deepgram dg mcp

Cursor

プロジェクトの .cursor/mcp.json に書き込むか、既存の設定にマージします。

{
  "mcpServers": {
    "deepgram": {
      "type": "stdio",
      "command": "dg",
      "args": ["mcp"]
    }
  }
}

Windsurf

Cursor と同じオブジェクトを使い、プロジェクトの .windsurf/mcp.json に書き込むか、既存の設定にマージします。

恒久的にインストールしない場合

uvx と pipx run は必要に応じて deepctl を取得します。認証情報は引き続き dg login または DEEPGRAM_API_KEY から取得されます。

{
  "mcpServers": {
    "deepgram": {
      "command": "uvx",
      "args": ["deepctl", "mcp"]
    }
  }
}

その他のツール

• トランスポート： stdio
• コマンド： dg
• 引数： ["mcp"]

dg mcp --transport sse --port 8000 を実行すると、HTTP が必要なクライアント向けに SSE を提供します。

---

パス B — スタンドアロンの deepgram-mcp

CLI の他の機能を含まない MCP サーバーです。1 つのパッケージ、1 つのバイナリです。

pip install deepgram-mcp
export DEEPGRAM_API_KEY=your_key_here

deepgram-mcp は PyPI パッケージです。同じ名前の npm パッケージは無関係なサードパーティー製コードで、DEEPGRAM_API_KEY も要求するため、npx deepgram-mcp は実行しないでください。

Claude Code

claude mcp add deepgram -- deepgram-mcp

Cursor / Windsurf

.cursor/mcp.json または Windsurf の MCP 設定に記述するか、既存の設定にマージします。

{
  "mcpServers": {
    "deepgram": {
      "command": "deepgram-mcp",
      "env": {
        "DEEPGRAM_API_KEY": "your_key_here"
      }
    }
  }
}

--api-key は環境変数より優先され、--transport sse --port 8000 を指定すると SSE を提供します。 ソース：https://github.com/deepgram/mcp。

---

パス C — ホステッドのドキュメント MCP（認証情報不要）

https://developers.deepgram.com/_mcp/server を使用します。認証なしで応答し、API キーは不要です。ドキュメントの抜粋をソース URL とともに返す searchDocs というツールを 1 つ公開します。

これは単純な稼働確認用 URL ではありません。HEAD は 404 を返し、MCP の Accept: application/json, text/event-stream ヘッダーを付けた GET は 405 を返します。また、ヘッダーなしの GET は MCP 応答ではなく、サーバーの JSON 記述子を返します。サーバーを実際に確認できるのは POST の initialize のみです。これは 200 と serverInfo.name の fern-docs-mcp-server を返します。

curl -s -X POST https://developers.deepgram.com/_mcp/server \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

Claude Code

# Project scope
claude mcp add deepgram-docs --scope project --transport http https://developers.deepgram.com/_mcp/server

# User/global scope
claude mcp add deepgram-docs --transport http https://developers.deepgram.com/_mcp/server

Cursor

プロジェクトの .cursor/mcp.json に記述するか、既存の設定にマージします。

{
  "mcpServers": {
    "deepgram-docs": {
      "type": "http",
      "url": "https://developers.deepgram.com/_mcp/server"
    }
  }
}

Windsurf

プロジェクトの .windsurf/mcp.json に、上記の Cursor と同じオブジェクトを記述するか、既存の設定にマージします。

その他のツール

• 種類： HTTP
• URL： https://developers.deepgram.com/_mcp/server

kapa のエンドポイントは認証情報なしでは使えません

https://api.dx.deepgram.com/kapa/mcp と https://deepgram.mcp.kapa.ai はどちらも存在し、認証なしのリクエストに HTTP 401 と WWW-Authenticate: Bearer resource_metadata=... ヘッダーを返すため、MCP の OAuth フローを実装したクライアントならどちらにも接続できます。Deepgram API キーが使えるかどうかは、エンドポイントによって異なります。

• api.dx.deepgram.com/kapa/mcp は Deepgram API キーを受け付けます。 Authorization: Token <KEY> または Authorization: Bearer <KEY> のいずれかでキーを送ると、initialize は deepgram-mcp-relay から 200 を返します。無効なキーの場合は 401 が返ります。tools/list はパス A および B と同じ search_deepgram_knowledge_sources ツールを 1 つ返すため、これは同じサーバーのホステッド HTTP 版です。キーは持っているものの、何もインストールできないユーザーに便利です。キーはヘッダーで渡してください。そうしないと、クライアントは OAuth にフォールバックします。

  claude mcp add deepgram-relay --transport http https://api.dx.deepgram.com/kapa/mcp \
    --header "Authorization: Token $DEEPGRAM_API_KEY"
  

• deepgram.mcp.kapa.ai は Deepgram API キーを受け付けません。 どちらのスキームでも、Deepgram API キーを使うと 401 が返ります。接続するには OAuth が必要です。

どちらもセットアップ不要の方法ではありません。その場合は /_mcp/server を使用してください。

---

ステップ 4：確認する

• Claude Code — /reload-plugins を実行すると、再起動せずにすぐ有効になります。
• Cursor / Windsurf / その他 — ツールの再起動または再読み込みが必要な場合があります。

次に、サーバーが設定されたことをユーザーに伝え、説明する前に実際に何を公開しているかを確認してください。ツール名を記憶で挙げるのではなく、クライアントにツール一覧を取得させてください。

パス C の場合は、次の内容を追加します。

ツールから Deepgram のドキュメントを直接検索できるようになりました。API パラメーター、音声エージェント、モデルの機能について質問してみてください。

詳細については、Deepgram Agentic Tools を案内してください。2 つの kapa URL、https://api.dx.deepgram.com/kapa/mcp と https://deepgram.mcp.kapa.ai には認証情報が必要です。認証なしの initialize は 401 を返します。認証情報が不要な方法は、Docs MCP サーバーの https://developers.deepgram.com/_mcp/server です。

トラブルシューティング

Error: DEEPGRAM_API_KEY is not set in the configuration file (...config.yaml) or environment variable. 続けて Run deepctl login to configure the CLI with your Deepgram account. → 認証情報がないパス A です。dg mcp は何も提供する前に終了コード 1 で終了します。dg login を実行するか、 DEEPGRAM_API_KEY を設定してください。dg whoami で確認します。

Error: No API key. Set DEEPGRAM_API_KEY or use --api-key. → 認証情報がないパス B です。DEEPGRAM_API_KEY をエクスポートするか、サーバーの env ブロックに設定するか、 --api-key を渡してください。

claude mcp list に ! Needs authentication と表示される、または HTTP 401 {"status_code":401,"detail":"Authentication required"} / {"error":"invalid_token"} が返される → 認証情報なしで kapa エンドポイントを指定しています。認証不要の https://developers.deepgram.com/_mcp/server に切り替えてください。 api.dx.deepgram.com/kapa/mcp を使い続ける場合は、--header "Authorization: Token $DEEPGRAM_API_KEY" を追加してください。この エンドポイントでは Deepgram API キーを使用できます。deepgram.mcp.kapa.ai では API キーは使えません。代わりにクライアントの OAuth フローを実行してください。

Server "deepgram-docs" is defined in multiple scopes with different endpoints → 以前の設定で、ユーザースコープに kapa URL の deepgram-docs が登録されており、今回、プロジェクトスコープに別の URL が追加されています。OAuth トークンはエンドポイントごとに保存されるため、片方で認証してももう片方には引き継がれません。どちらか一方を残してください。claude mcp remove deepgram-docs -s user（または -s project）を実行します。追加する前に claude mcp get deepgram-docs で既存のエントリを確認し、両方を残したい場合は別のサーバー名を選んでください。

起動時に streamablehttp_client に関する ImportError が表示される → 互換性のない mcp パッケージが使われています。deepgram-mcp は mcp.client.streamable_http から streamablehttp_client をインポートしますが、これは mcp 2.0 で削除されました。クリーンな環境にインストールするか、 mcp>=1.0.0,<2.0.0 に固定してください。deepctl をインストールすると、自動的にこのバージョンに固定されます。

サーバーは接続されるが、想定より少ないツールしか公開されない → 想定どおりです。パス A と B は実行時に Deepgram からツールの一覧を取得するため、パッケージのバージョンから想定される内容ではなく、その時点で API が提供している内容が反映されます。新しいツールを取得するには再接続してください。

パス A で上記以外の問題が発生する → dg --version が正常に動作し、ターミナルで dg mcp をエラーなく実行できることを確認してください。その後、 dg update --check-only を実行して、新しいリリースがあるか確認します。

ソース

• Deepgram CLI：https://github.com/deepgram/cli
• deepgram-mcp：https://github.com/deepgram/mcp
• Deepgram Agentic Tools：https://developers.deepgram.com/developer-tools/agentic-tools