EngrAmo

engramo-mcp

MCP server for EngrAmo, the spaced-repetition flashcard platform.

Hosted server

The hosted server at https://mcp.engramo.app/ needs no installation. It supports OAuth 2.0 with Dynamic Client Registration: your client sends you to the EngrAmo sign-in page, you sign in with your EngrAmo email and password and approve — no API token to paste. There is no sign-up on that page, so create your account in the EngrAmo app first. Setup guides: Claude and ChatGPT; the public docs are at https://engramo.app/connect/. You can revoke access any time in the EngrAmo app under Settings → Connected apps.

Prerequisites

• An EngrAmo account
• An EngrAmo API token — generate one from your account's Settings → API Tokens page. Only needed for the local (stdio) setups below and for remote clients without OAuth; the hosted connectors use OAuth instead.

Environments

engramo-mcp is environment-agnostic — the binary itself has no baked-in "dev" or "prod." Which server it talks to is controlled entirely by the ENGRAMO_API_URL you set in your client config, paired with a token minted from that same environment:

Dev and prod are separate backends with separate accounts. A token minted from one will not authenticate against the other — if you switch ENGRAMO_API_URL, you must also swap in a token generated from that same environment's Settings → API Tokens page.

ENGRAMO_API_URL vs the MCP server URL — these are not interchangeable. ENGRAMO_API_URL is the plain EngrAmo backend; it's never something a client connects to directly. In stdio config (Claude Desktop, Claude Code, Codex, VS Code, Cursor, Windsurf, Gemini CLI, Antigravity stdio below), the client sets ENGRAMO_API_URL together with ENGRAMO_API_TOKEN, since the locally-launched binary calls the backend itself. In http/remote config (Antigravity remote, ChatGPT), the client instead points serverUrl at the MCP server's own URL (mcp.engramo.app / mcp-engramo.volmyr.com above) and authenticates separately per session — via OAuth by default, or a static Authorization: Bearer header if you'd rather skip the login prompt. ENGRAMO_API_URL still matters in http mode, but only as an env var set by whoever deploys engramo-mcp http — a client never sets it.

Installation

Install the MCP server globally so it's available as a system command:

npm install -g @engramo/mcp

Prebuilt binaries ship for macOS (arm64, x64), Linux (arm64, x64) and Windows (x64). On other platforms, build from source with cargo build --release.

Verify the installation:

engramo-mcp --version

Alternatively, skip installation entirely and use npx -y @engramo/mcp in your client config — npm will download the binary automatically on first use.

Choosing a client

Any MCP client works. Local text-to-speech needs a stdio (locally launched) connection, so remote-only clients never get it.

Claude Desktop

One-click extension (recommended)

1. Download engramo.mcpb from the latest release (macOS on Intel and Apple Silicon, Windows x64, Linux x64 and arm64).
2. Double-click it (or drag it onto Claude Desktop) and click Install. Claude Desktop warns that the developer isn't verified by Anthropic; it shows this for every extension installed from a file.
3. Paste your EngrAmo API token, and optionally your Gemini API keys (comma-separated) to enable card audio. Claude Desktop stores both in the OS keychain.

No Node.js and no config file. Change the token or keys later under Settings → Extensions → EngrAmo → Configure. The extension doesn't auto-update: install the new engramo.mcpb to upgrade. Its tools are available in Chat conversations, not in Claude Desktop's Code mode. The bundle is built from mcpb/manifest.json by the release workflow. Verify a download with 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 (substituting the release tag), or compare it with the release's engramo.mcpb.sha256.

Manual config

Open Settings → Developer → Edit Config, or edit the file directly: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Using npx (no prior installation needed):

{
  "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 is optional — it enables list_tts_voices/generate_card_audio using your own Gemini quota; omit the line to disable. See Text-to-speech.

Using a global install (npm install -g @engramo/mcp):

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

After editing, fully quit Claude Desktop (⌘Q on macOS — closing the window isn't enough) and reopen it. If the server doesn't show up, check the logs at ~/Library/Logs/Claude/mcp-server-engramo.log (macOS) or %APPDATA%\Claude\logs\ (Windows). The Gemini key is never logged.

Claude (hosted connector)

Use the hosted server from claude.ai, Claude Desktop, or Claude mobile — no install, no token:

1. Settings → Connectors → Add custom connector
2. Paste https://mcp.engramo.app/
3. Connect, sign in with your EngrAmo account, and approve.

All hosted tools are then available. Like every remote connection, it has no local text-to-speech; use the Claude Desktop extension for that.

Claude Code

Register the server once for all your projects (--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 is optional — it enables list_tts_voices/generate_card_audio using your own Gemini quota; omit the -e ENGRAMO_TTS_GEMINI_API_KEYS=… line to disable. See Text-to-speech.

With a global install, replace npx -y @engramo/mcp with engramo-mcp.

Codex

The OpenAI Codex CLI and the Codex IDE extension share one config file, ~/.codex/config.toml. This is the way to use your ChatGPT account's models with local TTS (the ChatGPT app's remote connector can't have it):

Using npx (no prior installation needed):

[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 is optional — it enables list_tts_voices/generate_card_audio using your own Gemini quota; omit it from env to disable. See Text-to-speech.

Using a global install (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 mode)