EngrAmo README

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)

Add to .vscode/mcp.json (workspace), or run MCP: Open User Configuration from the Command Palette for a user-wide config. Use inputs with "password": true so VS Code prompts for the secrets and stores them itself instead of you writing them into the file. Note the top-level key is servers (not mcpServers):

Using npx (no prior installation needed):

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

With a global install, use "command": "engramo-mcp" and drop args.

Cursor

Add to ~/.cursor/mcp.json:

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"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

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"
      }
    }
  }
}

Antigravity

Antigravity supports both transports directly via its own config file — no separate remote-connector UI needed like ChatGPT's. Add to ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace-local):

stdio, via 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"
      }
    }
  }
}

Remote, over Streamable HTTP (point at a running engramo-mcp http deployment — see below). engramo-mcp supports OAuth 2.1 dynamic client registration, so Antigravity can handle authentication automatically — no token to paste or manage:

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

If you'd rather use a static token instead (no OAuth login prompt), add headers manually:

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

Text-to-speech is unavailable over the remote transport — use the stdio config above if you want generate_card_audio.

Use in ChatGPT (remote MCP over Streamable HTTP)

engramo-mcp also runs as a remote server, so it can be added to ChatGPT as a custom connector (developer mode) without installing anything locally. The hosted server at https://mcp.engramo.app/ already works this way. This is the same binary — the http subcommand instead of the default stdio — so a self-hosted deployment serves both Claude Desktop users (stdio) and ChatGPT users (HTTP) from one codebase.

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

This serves MCP over Streamable HTTP at POST / (root). Unlike stdio mode, there is no global ENGRAMO_API_TOKEN — every session authenticates with its own Authorization: Bearer <token> header, so one deployment safely serves many users at once (each session's calls to the EngrAmo API use only that session's token). Requests without a well-formed, non-empty bearer token are rejected with 401 before a session is created, and once a session exists every later request on it must carry the same token that opened it.

http mode also serves an unauthenticated GET /version that returns {"name","version"} (this binary's build version, read from Cargo.toml at compile time) — handy for deployment health and version probes without an MCP handshake.

In ChatGPT, enable developer mode (Settings → Connectors → Advanced → Developer mode), then add an app pointing at https://mcp.engramo.app/ (or your own deployment's https://<host>/). ChatGPT signs you in through OAuth: sign in with your EngrAmo account and approve — no API token needs to be pasted. (Clients without OAuth can instead send an EngrAmo API token from Settings → API Tokens as a static Authorization: Bearer header.) Once connected, prompts like "Make me a 10-card Spanish restaurant deck" or "Turn this conversation into flashcards" call generate_catalog_with_cards directly; open the result at https://study.engramo.app/catalog/<shortId> to study it.

generate_card_audio is never available through a ChatGPT connector — it's a remote connection, and local text-to-speech is stdio-only by design. To use your ChatGPT account's models with local TTS, use Codex instead.

A listing in the public ChatGPT app directory is coming; until then, add the app in developer mode as above.

ChatGPT plugin package (maintainers)

The directory listing is submitted on platform.openai.com/plugins as a plugin ZIP built from chatgpt-plugin/: plugin.json holds the listing metadata and mcp.json points at https://mcp.engramo.app/ with OAuth via dynamic client registration (no client ID or secret). Build it with:

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

The script copies the icon from mcpb/ and sets version from Cargo.toml. Upload a new ZIP (Plugins → EngrAmo → Upload new version) only when the listing metadata changes; tool and server changes are picked up by Rescan. The domain-verification token served at /.well-known/openai-apps-challenge comes from the portal and is set as the _OPENAI_APPS_CHALLENGE substitution on the prod Cloud Build trigger, not in this repo.

Bring-your-own-AI

Every deployment is bring-your-own-AI: the calling model (Claude, ChatGPT, …) does all generation — translation, dictionaries, phrasing — and engramo-mcp only persists the result via generate_card / generate_catalog_with_cards / generate_cards. This costs the EngrAmo account nothing beyond normal storage quotas, and needs no paid EngrAmo plan.

Environment variables

Available tools

Server info

Catalogs

Cards

Learning

Learning paths

Search

Media

AI generation (bring-your-own-AI)

Text-to-speech (stdio, opt-in)

Only present when ENGRAMO_TTS_GEMINI_API_KEYS is set (stdio mode only) — see Text-to-speech below.

Rich cards: dictionary, styling, images, audio

Beyond plain text, a card's face/back can carry:

A catalog can also have image_id (cover image) set the same way. None of this needs a paid EngrAmo plan — dictionary/translation are done by the calling model, images are entirely bring-your-own via upload_media (max ~10MB per file), and face audio is either bring-your-own the same way or generated locally with your own TTS key via generate_card_audio. See engramo://card-schema for the full schema and four worked examples, and docs/prompt-examples.md for ready-to-paste prompts covering all of this end to end.

Adding a lot of cards/media at once? upload_media is one file per call, fine for a handful of files through a chat client. For bulk imports (many cards, many audio files, in one request) see docs/bulk-import.md — a direct API recipe for CLI/scripted use (Claude Code, a terminal, a script), not a chat-driven MCP tool.

Text-to-speech (bring your own key)

Set ENGRAMO_TTS_GEMINI_API_KEYS and two extra tools appear: list_tts_voices and generate_card_audio. Given a list of card ids, generate_card_audio synthesizes speech for each card's face text with Gemini TTS, encodes it to MP3, uploads it to your own EngrAmo media, and attaches it as that card's audio_id — the same place a manually recorded upload_media file would go, just done for you.

stdio only, and on purpose. The key is read once, locally, from your own machine's environment and is never sent to EngrAmo or logged. In http mode the server is a shared, multi-tenant deployment — there is no per-session place to put a secret key that stays on the caller's machine — so ENGRAMO_TTS_GEMINI_API_KEYS is read only by stdio; in http mode it is ignored entirely (with a startup warning naming the variable, never its value) and neither tool is registered.

Why a namespaced variable instead of the standard GEMINI_API_KEY? GEMINI_API_KEY is the de-facto standard name set by the Gemini CLI, Google's own SDKs, and many developers' shell profiles. If engramo-mcp read it too, a key already sitting in your environment for an unrelated tool could silently start spending itself the moment you ran engramo-mcp stdio. engramo-mcp never reads GEMINI_API_KEY — only the explicit, namespaced ENGRAMO_TTS_GEMINI_API_KEYS opts you in.

Whose quota does this spend? Yours, not EngrAmo's. This is a different mechanism from the paid generate_tts_for_cards tool (ENGRAMO_ENABLE_PAID_AI), which spends EngrAmo's own metered TTS quota — generate_card_audio spends only your own Gemini API quota/billing, same as if you'd called Gemini directly.

Multiple keys / rotation. ENGRAMO_TTS_GEMINI_API_KEYS accepts a comma-separated list. On each synthesis call the keys are tried in a random order; a key that's rate-limited, rejected (invalid or revoked), or hits a transient error is skipped in favor of the next one, so one bad key in the list doesn't fail the whole call.

Limits. Up to 20 cards per generate_card_audio call, up to 500 characters of face text per card (longer cards are skipped, not truncated). Cards that already have face audio are skipped unless you pass overwrite: true, in which case the previous audio is not deleted — it stays in your EngrAmo media storage and keeps showing up in list_media. Call list_tts_voices first to see the configured model and voice catalog.

Getting a key. Create one for free at Google AI Studio.

Where the key goes. Every stdio client section above shows the exact place for ENGRAMO_TTS_GEMINI_API_KEYS — see Choosing a client. It's always one more entry next to ENGRAMO_API_TOKEN in the server's env:

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

Quick check. Ask the assistant to call list_tts_voices. If the tool is missing, the key isn't set (or the client wasn't restarted) or the client is using a remote connection.

Third-party licenses

The prebuilt binaries distributed via npm statically link LAME (LGPL-2.0) for the MP3 encoding generate_card_audio uses. See THIRD_PARTY_LICENSES for the full notice and source-availability terms.

Resources and Prompts

The server also exposes MCP Resources (live data readable as context):

And MCP Prompts (guided workflows):

Publishing to npm

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

The release workflow also publishes server.json to the official MCP Registry as app.engramo/mcp, after the GitHub release and npm packages exist. One-time setup, key rotation and bumping the pinned mcp-publisher are in docs/mcp-registry.md.

Contributing

Bug reports and pull requests are welcome at github.com/engramo-developer/engramo-mcp/issues.