EngrAmo

engramo-mcp

适用于 EngrAmo 间隔重复闪卡平台的 MCP 服务。

托管服务

托管服务 https://mcp.engramo.app/ 无需安装。它支持使用动态客户端注册的 OAuth 2.0：客户端会将你引导至 EngrAmo 登录页面，你使用 EngrAmo 邮箱和密码登录并授权即可——无需粘贴 API 令牌。该页面不提供注册功能，因此请先在 EngrAmo 应用中创建账户。EngrAmo 已收录于 Claude Connectors Directory。设置指南：Claude 和 ChatGPT；公开文档位于 https://engramo.app/connect/。你可以随时在 EngrAmo 应用的“设置”→“已连接的应用”中撤销访问权限。

前置条件

• 一个 EngrAmo 账户
• 一个 EngrAmo API 令牌——在账户的“设置”→“API 令牌”页面生成。仅以下本地 (stdio) 配置和不使用 OAuth 的远程客户端需要；托管连接器使用 OAuth。

环境

engramo-mcp 与环境无关——二进制文件本身没有内置“开发”或“生产”环境。它连接到哪个服务，完全由你在客户端配置中设置的 ENGRAMO_API_URL 决定，同时需搭配从同一环境生成的令牌：

环境	ENGRAMO_API_URL	MCP 服务 URL（仅限 http 传输）	适用对象
生产环境（以下所有示例中的默认值）	https://api.engramo.app	https://mcp.engramo.app	真实账户——除非有特殊原因，否则请使用此环境
开发环境	https://api-engram.volmyr.com	https://mcp-engramo.volmyr.com	仅供 EngrAmo 团队／内部测试

开发环境和生产环境是彼此独立的后端，账户也相互独立。 在一个环境中生成的令牌无法通过另一个环境的身份验证——如果切换 ENGRAMO_API_URL，也必须换成从同一环境的“设置”→“API 令牌”页面生成的令牌。

ENGRAMO_API_URL 与 MCP 服务 URL 不可互换。 ENGRAMO_API_URL 是 EngrAmo 后端的普通地址；客户端永远不会直接连接到它。在 stdio 配置中（下文的 Claude Desktop、 Claude Code、Codex、VS Code、Cursor、Windsurf、Gemini CLI、Antigravity stdio），客户端会同时设置 ENGRAMO_API_URL 和 ENGRAMO_API_TOKEN，因为本地启动的二进制文件会自行调用后端。在 http／远程配置中（Antigravity remote、ChatGPT）， 客户端则将 serverUrl 指向 MCP 服务自己的 URL（上文的 mcp.engramo.app／mcp-engramo.volmyr.com），并在每个会话中单独进行身份验证——默认使用 OAuth；如果你想跳过登录提示，也可以使用静态的 Authorization: Bearer 标头。ENGRAMO_API_URL 在 http 模式下仍然重要，但它只是由部署 engramo-mcp http 的人员设置的环境变量——客户端不会设置它。

安装

全局安装 MCP 服务，使其可作为系统命令使用：

npm install -g @engramo/mcp

我们提供适用于 macOS（arm64、x64）、Linux（arm64、x64）和 Windows（x64）的预编译二进制文件。在其他平台上，请通过 cargo build --release 从源代码构建。

验证安装：

engramo-mcp --version

也可以完全跳过安装，在客户端配置中使用 npx -y @engramo/mcp——npm 会在首次使用时自动下载二进制文件。

选择客户端

任何 MCP 客户端都可以。本地文本转语音需要通过 stdio （本地启动）连接，因此仅支持远程连接的客户端无法使用此功能。

客户端	模型	本地 TTS	设置
Claude（claude.ai、Desktop、mobile）	Claude	❌ — 仅支持托管连接器；有意不提供本地 TTS	Claude（托管连接器） — 推荐：从 Connectors Directory 安装，无需下载
Claude Desktop 扩展	Claude	✅	Claude Desktop — 用于卡片音频：一键安装扩展，无需 Node.js 或编辑配置；免费计划支持本地扩展
Claude Code	Claude	✅	Claude Code
Codex（CLI / IDE 扩展）	OpenAI 模型 — 使用 ChatGPT 账号登录	✅	Codex
VS Code（GitHub Copilot）	GPT / Claude / Gemini	✅	VS Code
Cursor	GPT / Claude / Gemini	✅	Cursor
Windsurf	GPT / Claude / Gemini	✅	Windsurf
Gemini CLI	Gemini	✅	Gemini CLI
Antigravity	Gemini / Claude / GPT	✅ stdio / ❌ 远程	Antigravity
ChatGPT	OpenAI 模型	❌ — 仅支持远程连接器（OAuth）；有意不提供本地 TTS	ChatGPT

Claude Desktop

大多数 Claude Desktop 用户应改为从 Connectors Directory 添加托管连接器： 无需下载、无需粘贴令牌，而且也适用于 claude.ai 和 mobile。如果要使用卡片音频，请使用下方的扩展；只有本地服务才能提供此功能。

一键安装扩展（用于卡片音频）

1. 从最新版本中下载 engramo.mcpb （支持 macOS Intel 和 Apple Silicon、Windows x64、Linux x64 和 arm64）。
2. 双击该文件（或将其拖到 Claude Desktop 上），然后点击 Install。Claude Desktop 会显示红色警告，提示该扩展可访问你电脑上的所有内容，且 Anthropic 尚未验证开发者。所有从文件安装的扩展都会显示此警告——Connectors Directory 已不再列出桌面扩展——而且警告内容属实：该扩展会以你的用户权限运行 engramo-mcp 二进制文件。
3. 粘贴你的 EngrAmo API 令牌，并可选择填写 Gemini API 密钥（以逗号分隔）以启用 卡片音频。Claude Desktop 会将两者存储在操作系统钥匙串中。

无需 Node.js，也无需配置文件。之后可在 Settings → Extensions → EngrAmo → Configure 中更改令牌或密钥。该扩展不会自动更新：安装新版 engramo.mcpb 即可升级。扩展的工具可在 Chat 对话中使用，不能在 Claude Desktop 的 Code 模式中使用。此安装包由发布工作流根据 mcpb/manifest.json 构建。请使用 gh attestation verify engramo.mcpb -R engramo-developer/engramo-mcp --signer-workflow engramo-developer/engramo-mcp/.github/workflows/release.yml --source-ref refs/tags/vX.Y.Z （将版本号替换为对应的发布标签）验证下载文件，或将其与发布版本中的 engramo.mcpb.sha256 进行比对。

手动配置

打开 设置 → 开发者 → 编辑配置，或直接编辑文件： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

使用 npx（无需预先安装）：

{
  "mcpServers": {
    "engramo": {
      "command": "npx",
      "args": ["-y", "@engramo/mcp"],
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "your-token",
        "ENGRAMO_TTS_GEMINI_API_KEYS": "your-gemini-key"
      }
    }
  }
}

ENGRAMO_TTS_GEMINI_API_KEYS 是可选项——启用后，可使用你自己的 Gemini 配额运行 list_tts_voices/generate_card_audio；省略此行即可禁用。参见文本转语音。

使用全局安装（npm install -g @engramo/mcp）：

{
  "mcpServers": {
    "engramo": {
      "command": "engramo-mcp",
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "your-token"
      }
    }
  }
}

编辑后，完全退出 Claude Desktop（macOS 上按 ⌘Q——仅关闭窗口并不足够），然后重新打开。 如果未显示该服务，请检查日志：~/Library/Logs/Claude/mcp-server-engramo.log（macOS）或 %APPDATA%\Claude\logs\（Windows）。Gemini 密钥绝不会写入日志。

Claude（托管连接器）

通过 claude.ai、Claude Desktop 或 Claude 移动应用使用托管服务——无需安装，也无需令牌：

1. 打开连接器目录中的 EngrAmo（或前往设置 → 连接器 → 浏览并搜索 EngrAmo）。
2. 连接，使用你的 EngrAmo 账户登录并批准。

这是一个社区连接器：Anthropic 进行了自动审核，但尚未验证该连接器，因此连接前 Claude 会显示一条简短提示。 如果无法通过目录添加——例如，你所在的组织对此有限制——也可以通过 URL 添加：前往设置 → 连接器 → 添加自定义连接器，粘贴 https://mcp.engramo.app/，然后点击连接。

之后即可使用所有托管工具。与所有远程连接一样，它不支持本地文本转语音；如需此功能，请使用 Claude Desktop 扩展。

Claude Code

注册一次，即可用于你的所有项目（--scope user）：

claude mcp add engramo --scope user \
  -e ENGRAMO_API_URL=https://api.engramo.app \
  -e ENGRAMO_API_TOKEN=your-token \
  -e ENGRAMO_TTS_GEMINI_API_KEYS=your-gemini-key \
  -- npx -y @engramo/mcp

ENGRAMO_TTS_GEMINI_API_KEYS 是可选项——启用后，可使用你自己的 Gemini 配额运行 list_tts_voices/generate_card_audio；省略 -e ENGRAMO_TTS_GEMINI_API_KEYS=… 这一行即可禁用。参见 文本转语音。

如果已全局安装，请将 npx -y @engramo/mcp 替换为 engramo-mcp。

Codex

OpenAI Codex CLI 和 Codex IDE 扩展共用一个配置文件 ~/.codex/config.toml。如果要将 ChatGPT 账户的模型与本地 TTS 搭配使用，请采用此配置方式（ChatGPT 应用的远程连接器不支持本地 TTS）：

使用 npx（无需预先安装）：

[mcp_servers.engramo]
command = "npx"
args = ["-y", "@engramo/mcp"]
tool_timeout_sec = 300  # default 60s; a 20-card generate_card_audio batch can take longer
env = { ENGRAMO_API_URL = "https://api.engramo.app", ENGRAMO_API_TOKEN = "your-token", ENGRAMO_TTS_GEMINI_API_KEYS = "your-gemini-key" }

ENGRAMO_TTS_GEMINI_API_KEYS 是可选项——启用后，可使用你自己的 Gemini 配额运行 list_tts_voices/generate_card_audio；从 env 中省略该项即可禁用。参见文本转语音。

使用全局安装（npm install -g @engramo/mcp）：

[mcp_servers.engramo]
command = "engramo-mcp"
env = { ENGRAMO_API_URL = "https://api.engramo.app", ENGRAMO_API_TOKEN = "your-token" }

VS Code（GitHub Copilot Agent 模式）

将配置添加到 .vscode/mcp.json（工作区），或从命令面板运行 MCP: Open User Configuration 以进行用户级配置。使用 inputs 和 "password": true，让 VS Code 提示输入密钥并自行保存，而不是由你将密钥写入文件。请注意，顶层键为 servers（而非 mcpServers）：

使用 npx（无需预先安装）：

{
  "inputs": [
    { "type": "promptString", "id": "engramo-token", "description": "EngrAmo API token", "password": true },
    { "type": "promptString", "id": "gemini-key", "description": "Gemini API key (for TTS)", "password": true }
  ],
  "servers": {
    "engramo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@engramo/mcp"],
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "${input:engramo-token}",
        "ENGRAMO_TTS_GEMINI_API_KEYS": "${input:gemini-key}"
      }
    }
  }
}

ENGRAMO_TTS_GEMINI_API_KEYS 是可选项——启用后，可使用你自己的 Gemini 配额运行 list_tts_voices/generate_card_audio；省略该行（以及 gemini-key 输入项）即可禁用。参见 文本转语音。

如果已全局安装，请使用 "command": "engramo-mcp" 并删除 args。

Cursor

添加到 ~/.cursor/mcp.json：

使用 npx（无需预先安装）：

{
  "mcpServers": {
    "engramo": {
      "command": "npx",
      "args": ["-y", "@engramo/mcp"],
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "your-token",
        "ENGRAMO_TTS_GEMINI_API_KEYS": "your-gemini-key"
      }
    }
  }
}

ENGRAMO_TTS_GEMINI_API_KEYS 是可选项——启用后，可使用你自己的 Gemini 配额运行 list_tts_voices/generate_card_audio；省略该行即可禁用。参见文本转语音。

使用全局安装（npm install -g @engramo/mcp）：

{
  "mcpServers": {
    "engramo": {
      "command": "engramo-mcp",
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "your-token"
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

使用 npx（无需预先安装）：

{
  "mcpServers": {
    "engramo": {
      "command": "npx",
      "args": ["-y", "@engramo/mcp"],
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "your-token",
        "ENGRAMO_TTS_GEMINI_API_KEYS": "your-gemini-key"
      }
    }
  }
}

ENGRAMO_TTS_GEMINI_API_KEYS 是可选项 — 设置后，可使用你自己的 Gemini 配额调用 list_tts_voices/generate_card_audio；省略此行即可禁用。请参阅文本转语音。

使用全局安装（npm install -g @engramo/mcp）：

{
  "mcpServers": {
    "engramo": {
      "command": "engramo-mcp",
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "your-token"
      }
    }
  }
}

Gemini CLI

添加到 ~/.gemini/settings.json：

使用 npx（无需预先安装）：

{
  "mcpServers": {
    "engramo": {
      "command": "npx",
      "args": ["-y", "@engramo/mcp"],
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "your-token",
        "ENGRAMO_TTS_GEMINI_API_KEYS": "your-gemini-key"
      }
    }
  }
}

ENGRAMO_TTS_GEMINI_API_KEYS 是可选项 — 设置后，可使用你自己的 Gemini 配额调用 list_tts_voices/generate_card_audio；省略此行即可禁用。请参阅文本转语音。

使用全局安装（npm install -g @engramo/mcp）：

{
  "mcpServers": {
    "engramo": {
      "command": "engramo-mcp",
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "your-token"
      }
    }
  }
}

Antigravity

Antigravity 可通过自己的配置文件直接支持这两种传输方式 — 无需像 ChatGPT 那样使用单独的远程连接器界面。添加到 ~/.gemini/config/mcp_config.json（全局）或 .agents/mcp_config.json （工作区本地）：

stdio，通过 npx（无需预先安装）：

{
  "mcpServers": {
    "engramo": {
      "command": "npx",
      "args": ["-y", "@engramo/mcp"],
      "env": {
        "ENGRAMO_API_URL": "https://api.engramo.app",
        "ENGRAMO_API_TOKEN": "your-token"
      }
    }
  }
}

远程，通过 Streamable HTTP（指向正在运行的 engramo-mcp http 部署 — 见下文）。 engramo-mcp 支持 OAuth 2.1 动态客户端注册，因此 Antigravity 可自动处理身份验证 — 无需粘贴或管理令牌：

{
  "mcpServers": {
    "engramo": {
      "serverUrl": "https://mcp.engramo.app/"
    }
  }
}

如果你更想使用静态令牌（不显示 OAuth 登录提示），请手动添加 headers：

{
  "mcpServers": {
    "engramo": {
      "serverUrl": "https://mcp.engramo.app/",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

远程传输方式不支持文本转语音 — 如果要使用 generate_card_audio，请使用上面的 stdio 配置。

在 ChatGPT 中使用（通过 Streamable HTTP 的远程 MCP）

engramo-mcp 也可以作为远程服务运行，因此可将其作为自定义连接器（开发者模式）添加到 ChatGPT，无需在本地安装任何内容。托管服务 https://mcp.engramo.app/ 已采用这种方式运行。这是同一个二进制文件 — 使用 http 子命令而非默认的 stdio — 因此，一个可自托管的部署即可通过同一代码库同时为 Claude Desktop 用户（stdio）和 ChatGPT 用户（HTTP）提供服务。

ENGRAMO_API_URL=https://api.engramo.app MCP_BIND_ADDR=0.0.0.0:8080 engramo-mcp http

该服务通过 Streamable HTTP 在根路径 POST / 提供 MCP。与 stdio 模式不同，这里没有全局的 ENGRAMO_API_TOKEN — 每个会话都使用自己的 Authorization: Bearer <token> 请求头进行身份验证，因此一个部署可安全地同时为许多用户提供服务（每个会话对 EngrAmo API 的调用只使用该会话自己的令牌）。没有格式正确且非空的 bearer 令牌的请求会在创建会话前被拒绝，并返回 401；会话建立后，该会话上的每个后续请求都必须携带创建会话时使用的相同令牌。

http 模式还提供无需身份验证的 GET /version，返回 {"name","version"}（此二进制文件的构建版本，在编译时从 Cargo.toml 读取） — 可用于部署运行状况和版本探测，无需 MCP 握手。

在 ChatGPT 中，启用开发者模式（设置 → 连接器 → 高级 → 开发者模式），然后添加一个指向 https://mcp.engramo.app/（或你自己的部署地址 https://<host>/）的应用。ChatGPT 会通过 OAuth 为你登录：使用你的 EngrAmo 账户登录并批准即可 — 无需粘贴 API 令牌。（不支持 OAuth 的客户端可以改为发送“设置 → API Tokens”中的 EngrAmo API 令牌，将其作为静态 Authorization: Bearer 请求头。）连接后，像 “为我制作一套包含 10 张卡片的西班牙餐厅主题卡组” 或 “把这段对话转换成抽认卡” 这样的提示词会直接调用 generate_catalog_with_cards；打开 https://study.engramo.app/catalog/<shortId> 即可学习。

通过 ChatGPT 连接器始终无法使用 generate_card_audio — 这是远程连接，而本地文本转语音按设计仅支持 stdio。若要结合本地文本转语音使用 ChatGPT 账户的模型，请改用 Codex。

公开的 ChatGPT 应用目录即将上线；在此之前，请按上述说明在开发者模式下添加应用。

ChatGPT 插件包（维护者）

在 platform.openai.com/plugins 提交目录 listing 时，需上传一个由 chatgpt-plugin/ 构建的插件 ZIP：plugin.json 保存 listing 元数据，mcp.json 指向 https://mcp.engramo.app/，并通过动态客户端注册使用 OAuth（无需客户端 ID 或密钥）。使用以下命令构建：

./chatgpt-plugin/build.sh   # → target/engramo-chatgpt-plugin.zip

脚本会从 mcpb/ 复制图标，并从 Cargo.toml 设置 version。仅当 listing 元数据发生变化时，才上传新的 ZIP（Plugins → EngrAmo → Upload new version）；工具和服务的变更通过 Rescan 获取。/.well-known/openai-apps-challenge 提供的域名验证令牌来自门户，并作为 _OPENAI_APPS_CHALLENGE 替换项设置在 prod Cloud Build 触发器上，不在此仓库中。

自带 AI

每个部署都采用自带 AI模式：调用模型（Claude、ChatGPT 等）负责所有生成工作——翻译、词典、措辞等——而 engramo-mcp 仅通过 generate_card / generate_catalog_with_cards / generate_cards 保存结果。除常规存储配额外，这不会给 EngrAmo 账户带来任何费用，也无需付费的 EngrAmo 套餐。

环境变量

变量	默认值	说明
ENGRAMO_API_URL	https://api.engramo.app	EngrAmo API 的基础 URL
ENGRAMO_API_TOKEN	（stdio 必需）	你的 EngrAmo API 令牌。在 http 模式下不使用；每个会话通过 Authorization: Bearer 标头提供自己的令牌。
MCP_BIND_ADDR	0.0.0.0:8080	http 模式的绑定地址
MCP_PUBLIC_URL	（未设置）	仅限 http 模式——此部署自身的公开 URL（纯源地址，不含路径——端点由 / 提供），例如 https://mcp.engramo.app。同时会将该主机加入入站请求允许列表；未设置时，所有请求都会被拒绝（参见 MCP_ALLOWED_HOSTS）。
MCP_ALLOWED_HOSTS	（未设置）	仅限 http 模式——除根据 MCP_PUBLIC_URL 派生的主机外，额外允许的、以逗号分隔的主机名或 host:port 值。仅在有额外入口时需要（例如，Cloud Run 服务的自有 *.run.app 回退 URL 与自定义域名并存）。
ENGRAMO_TTS_GEMINI_API_KEYS	（未设置 → 不提供 TTS 工具）	仅限 stdio。 你自己的 Gemini API 密钥，或以逗号分隔的密钥列表。启用 list_tts_voices / generate_card_audio。在 http 模式下会忽略此项（并在启动时发出警告）——参见下文的文本转语音。
ENGRAMO_TTS_PROVIDER	gemini	仅限 stdio。 TTS 引擎选择器。目前仅支持 gemini；无法识别的值会导致启动失败。
ENGRAMO_TTS_MODEL	gemini-3.8-flash-tts	仅限 stdio。 Gemini TTS 模型 ID。
ENGRAMO_TTS_VOICE	Puck	仅限 stdio。 当 generate_card_audio 调用未指定声音时使用的默认声音。

可用工具

服务信息

工具	说明
get_server_version	获取此 MCP 服务自身的构建版本（不是目录或卡片的 version 字段）
get_subscription_usage	查看你的 userId、套餐和功能，以及每项限额的用量、剩余量、是否无限制或不包含在套餐内、限额周期（终身或每月，以及每日／每小时子限额）和重置时间（UTC）。出现“Quota exceeded”或“Not included in your plan”错误后调用此工具。

目录

工具	描述
list_catalogs	列出所有闪卡目录；filter（own 或 shared）可将结果限制为你拥有的目录或他人与你共享的目录，speaking_only 可将结果限制为已开启跟读练习的目录
get_catalog	按 ID 获取单个目录
update_catalog	更新目录名称或描述
set_catalog_shadowing	开启或关闭目录的跟读练习，或更改其语言
share_catalog	按用户 ID（UUID，而非电子邮件）将你拥有的目录共享给其他用户，并授予 viewer（默认）或 editor 权限；重新共享会更改对方的权限级别。返回完整的协作者列表。请向他人索取其用户 ID；他们可以通过 get_subscription_usage 获取
unshare_catalog	移除其他用户对你拥有的目录的访问权限。返回剩余协作者
list_catalog_shares	列出目录的共享对象及其访问级别（所有者或编辑者）
delete_catalog	删除目录

卡片

工具	描述
list_cards	列出目录中的卡片
get_card	按 ID 获取单张卡片
update_card	更新卡片内容
delete_card	删除卡片

学习

工具	描述
get_due_cards	获取今天到期需要复习的卡片
get_all_learning_cards	获取学习队列中的所有卡片
add_card_to_learning	将卡片添加到学习队列
add_catalog_to_learning	将目录中的所有卡片添加到学习队列

学习路径

工具	描述
list_learning_paths	列出所有学习路径
get_learning_path	按 ID 获取单个学习路径
create_learning_path	创建新的学习路径
activate_learning_path	激活学习路径
deactivate_learning_path	停用学习路径

搜索

工具	描述
search_global	对所有内容进行全文搜索
search_catalogs	在指定目录中搜索

媒体

工具	描述
list_media	列出已上传的媒体资源
upload_media	上传已有文件（语音录音、图像），并获取可附加到卡片或目录的 media_id

AI 生成（自带 AI）

工具	描述
generate_card	创建闪卡——调用模型自行完成翻译和措辞
generate_catalog_with_cards	一次调用创建包含卡片的目录——同样使用自带 AI 模型
generate_cards	向现有目录添加多张卡片——同样使用自带 AI 模型

文本转语音（stdio，可选）

仅在设置了 ENGRAMO_TTS_GEMINI_API_KEYS 时提供（仅限 stdio 模式）——见下文的 文本转语音。

工具	描述
list_tts_voices	列出已配置的 TTS 引擎、模型、默认语音和可用语音。不会发起网络请求。
generate_card_audio	为最多 20 张卡片的 FACE 面合成语音，将其上传到你自己的媒体库并附加到卡片——使用你自己的 Gemini 密钥和配额

富媒体卡片：词典、样式、图片、音频

除了纯文本外，卡片的 face/back 还可以包含：

字段	作用
dictionary	单词 → 翻译映射，在应用中显示为可点击的高亮内容
rich_text	文本中的样式片段（粗体、颜色、等宽字体）
style	为整个正面或背面设置字体、颜色、背景和对齐方式
audio_id	你自己的音频（录音、自己使用 TTS 生成的片段）——先使用 upload_media 上传，或调用 generate_card_audio 自动设置（仅限 stdio，见下文）
visual_id + visual_type	你自己的图片/视频，方式与 audio_id 相同

也可以用同样的方式为目录设置 image_id（封面图片）。以上功能都不需要付费的 EngrAmo 计划——词典/翻译由调用模型完成；图片完全由你自行提供，通过 upload_media 上传（每个文件最大约 10MB）；正面音频则可以用同样的方式自行提供，或使用自己的 TTS 密钥通过 generate_card_audio 在本地生成。完整架构和四个示例请参阅 engramo://card-schema；涵盖以上完整流程、可直接粘贴使用的提示词请参阅 docs/prompt-examples.md。

要一次添加大量卡片/媒体吗？ upload_media 每次调用处理一个文件，通过聊天客户端上传少量文件很方便。批量导入（在一个请求中导入多张卡片、多个音频文件）请参阅 docs/bulk-import.md——这是供 CLI/脚本使用的直接 API 操作指南（Claude Code、终端、脚本），并非由聊天驱动的 MCP 工具。

文本转语音（自带密钥）

设置 ENGRAMO_TTS_GEMINI_API_KEYS 后，会出现两个额外工具：list_tts_voices 和 generate_card_audio。给定一组卡片 ID，generate_card_audio 会使用 Gemini TTS 为每张 卡片的正面文本合成语音，将其编码为 MP3，上传到你自己的 EngrAmo 媒体库，并将其附加为该卡片的 audio_id——位置与手动录制后通过 upload_media 上传的文件相同，只是这些步骤由工具代劳。

仅限 stdio，这是有意为之。 密钥只从你自己的机器环境中本地读取一次，绝不会发送到 EngrAmo，也不会记录到日志中。在 http 模式下，服务是一个供多个租户共享的部署——没有可供密钥留在调用方机器上的会话级位置——因此 ENGRAMO_TTS_GEMINI_API_KEYS 仅由 stdio 读取；在 http 模式下会被完全忽略（启动时会显示包含变量名、但不含其值的警告），并且不会注册这两个工具。

为什么使用带命名空间的变量，而不是标准的 GEMINI_API_KEY？ GEMINI_API_KEY 是 Gemini CLI、Google 自家的 SDK 以及许多开发者的 shell 配置文件所设置的事实标准名称。如果 engramo-mcp 也读取它，那么环境中已有的、用于其他工具的密钥可能会在你运行 engramo-mcp stdio 时悄悄开始被消耗。engramo-mcp 绝不会读取 GEMINI_API_KEY——只有明确设置带命名空间的 ENGRAMO_TTS_GEMINI_API_KEYS 才会启用此功能。

消耗的是谁的配额？ 是你的配额，不是 EngrAmo 的。这与付费工具 generate_tts_for_cards（ENGRAMO_ENABLE_PAID_AI）使用的机制不同；后者消耗 EngrAmo 自己的计量式 TTS 配额，而 generate_card_audio 只消耗你自己的 Gemini API 配额／费用，就像你直接调用 Gemini 一样。

多个密钥／轮换。 ENGRAMO_TTS_GEMINI_API_KEYS 接受以逗号分隔的密钥列表。每次合成调用都会以随机顺序尝试这些密钥；如果某个密钥受到速率限制、被拒绝（无效或已撤销）或遇到暂时性错误，就会跳过它并尝试下一个，因此列表中一个有问题的密钥不会导致整个调用失败。

限制。 每次 generate_card_audio 调用最多处理 20 张卡片，每张卡片的正面文本最多 500 个字符（更长的卡片会被跳过，不会截断）。已有正面音频的卡片会被跳过，除非你传入 overwrite: true；此时不会删除原有音频——它会保留在你的 EngrAmo 媒体存储中，并继续显示在 list_media 的结果中。请先调用 list_tts_voices，查看已配置的模型和语音目录。

获取密钥。 在 Google AI Studio 免费创建密钥。

密钥应放在哪里。 上文每个 stdio 客户端章节都展示了 ENGRAMO_TTS_GEMINI_API_KEYS 的确切设置位置——请参阅选择客户端。它始终是在服务的 env 中、ENGRAMO_API_TOKEN 旁边再添加一项：

"env": {
  "ENGRAMO_API_URL": "https://api.engramo.app",
  "ENGRAMO_API_TOKEN": "your-token",
  "ENGRAMO_TTS_GEMINI_API_KEYS": "your-gemini-key"
}

快速检查。 请助手调用 list_tts_voices。如果缺少此工具，说明尚未设置密钥（或客户端尚未重启），或者客户端正在使用远程连接。

第三方许可证

通过 npm 分发的预构建二进制文件会静态链接 LAME（LGPL-2.0），以供 generate_card_audio 使用的 MP3 编码。完整声明和源代码可用性条款请参阅 THIRD_PARTY_LICENSES。

资源和提示词

该服务还会公开 MCP 资源（可作为上下文读取的实时数据）：

URI	描述
engramo://card-schema	CardContent JSON 架构，包含验证规则和示例
engramo://catalogs	所有目录（id、name、card_count）
engramo://learning/due	今天到期需要复习的卡片
engramo://learning/stats	学习统计数据（due_count、total_count）
engramo://learning-paths	所有学习路径（id、name）
engramo://subscription	您的 userId、plan、limits 和 usage（与 get_subscription_usage 中的视图相同）

以及 MCP 提示词（引导式工作流）：

提示词	描述
review_session	开始引导式间隔重复复习
create_flashcard	为某个主题创建高质量的闪卡
create_language_deck	创建经过样式设计、翻译并附有词典注释的语言学习卡组 — 参见 docs/prompt-examples.md
explain_card	通过示例深入讲解一张闪卡
study_plan	根据您的目录制定结构化学习计划

发布到 npm

git tag vx.y.z                                                                                                                                                                                                      
git push origin vx.y.z

发布工作流还会在 GitHub 发布版本和 npm 包发布后，将 server.json 发布到官方 MCP Registry，名称为 app.engramo/mcp。一次性设置、密钥轮换以及升级固定版本的 mcp-publisher，请参阅 docs/mcp-registry.md。

参与贡献

欢迎通过 github.com/engramo-developer/engramo-mcp/issues 提交 Bug 报告和拉取请求。