setup-mcp

安装 Deepgram MCP 服务

你正在为用户配置 Deepgram MCP 集成。请按照以下步骤操作。

第 1 步：选择路径

共有三条路径。根据用户是否已有或需要 Deepgram API key 来选择。

路径	服务	凭据	安装占用
A	Deepgram CLI MCP 代理（dg mcp）	Deepgram API key 必需	完整 CLI（deepctl）
B	独立的 deepgram-mcp	Deepgram API key 必需	一个 Python 包
C	托管的文档 MCP（/_mcp/server）	无	无需安装任何内容

决策规则：

• 用户已有 CLI，或者也需要 dg listen / dg speak / dg init → 路径 A。
• 用户有 API key，但只想要 MCP 服务，不需要 CLI → 路径 B。
• 用户没有 API key，或者想要一条命令就能跑起来的东西 → 路径 C。

路径 A/B 还有一个通过 key 认证的托管变体，位于 api.dx.deepgram.com/kapa/mcp， 无需安装任何内容 —— 参见下文“kapa 端点并非无需凭据”。

路径 A 和 B 是同一个服务：dg mcp 封装了 deepgram-mcp 包。两者都代理 Deepgram 的开发者 API，并在运行时从 Deepgram 获取其工具列表，因此新工具 会在重新连接后出现，无需升级包。在撰写本文时，该列表只有一个 文档与知识源搜索工具（search_degram_knowledge_sources）—— 请查看 用户客户端中的 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，会安装三个可互换的二进制文件 —— 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 只会在第三方 formula 被信任后才加载它， 而 brew install deepgram/tap/deepgram 会信任该 formula，相比之下 brew tap deepgram/tap && brew install deepgram 会失败，直到单独执行 brew trust 步骤。 该 tap formula 固定为 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 获取 key。

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

写入或合并到项目的 .windsurf/mcp.json，使用与上面 Cursor 相同的对象。

无需永久安装

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 则改为提供 SSE 服务，适用于需要 HTTP 的客户端。

---

路径 B — 独立的 deepgram-mcp

不带 CLI 其余部分的 MCP 服务。一个包，一个二进制文件。

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 密钥，并暴露一个工具 searchDocs，返回带有来源 URL 的文档段落。

它不是一个普通的存活探测 URL。HEAD 返回 404，带 MCP Accept: application/json, text/event-stream 头的 GET 返回 405，而裸 GET 返回 服务器的 JSON 描述符而非 MCP 响应。只有 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 工具，因此这是同一服务的托管 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 密钥在两种方案下都会得到 401。OAuth 是 唯一的进入方式。

两者都不是零配置选项 —— 那请使用 /_mcp/server。

---

第 4 步：确认

• Claude Code — 运行 /reload-plugins 立即激活，无需重启。
• Cursor / Windsurf / 其他 — 用户可能需要重启或重新加载他们的工具。

然后告诉用户该服务已配置好，并在描述它之前先检查它实际暴露了什么 —— 让客户端列出其工具， 而不是凭记忆说出工具名称。

对于路径 C，补充：

你的工具现在可以直接搜索 Deepgram 的文档 —— 试着询问 API 参数、语音 Agent 或模型能力。

将他们链接到 Deepgram Agentic Tools 了解详情。它的两个 kapa URL，https://api.dx.deepgram.com/kapa/mcp 和 https://deepgram.mcp.kapa.ai，需要凭证：未认证的 initialize 返回 401。 位于 https://developers.deepgram.com/_mcp/server 的 Docs MCP 服务是无需凭证的路径。

故障排查

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 key。在 deepgram.mcp.kapa.ai 上 API key 不起作用；请让 客户端运行其 OAuth 流程。

Server "deepgram-docs" is defined in multiple scopes with different endpoints → 先前的设置将 deepgram-docs 注册在用户作用域下的某个 kapa URL，而这次在项目作用域下添加了 另一个不同的 URL。OAuth token 按端点存储，因此认证其中一个不会 延续到另一个。只保留一个：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