Mochi MCP Server
A Model Context Protocol server that enables AI agents (Claude, Codex, etc.) to manage your Mochi.cards flashcards.
Features
- Browse decks and cards
- Search cards by content or tags
- Create/Update cards with two-phase commit (preview before applying)
- Delete cards with typed confirmation (safety first)
- Robust safety - deck deletion disabled by default
Quick Start
# Install
npm install
# Build
npm run build
# Run (needs your Mochi API key)
MOCHI_API_KEY=your_key_here node dist/index.js
Get your API key from the Mochi app: Settings → Account → API Key.
Usage with Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"mochi": {
"command": "node",
"args": ["/path/to/mochi-mcp/dist/index.js"],
"env": {
"MOCHI_API_KEY": "your_api_key"
}
}
}
}
Then ask Claude: "List my Mochi decks" or "Search for cards about gradients".
Tools
Read Operations
| Tool | Description |
|---|---|
list_decks | List all decks |
get_deck | Get deck with card list |
get_card | Get full card content |
get_cards | Get multiple cards by ID |
search_cards | Search by text, tags, or date. Returns rich results (deckId, createdAt, etc.) |
list_cards_page | Paginated card listing with bookmark |
find_deck_by_name | Find decks by name (case-insensitive partial match) |
Write Operations (Two-Phase Commit)
| Tool | Description |
|---|---|
create_card_preview | Preview new card → returns token |
apply_create_card | Apply creation with token |
update_card_preview | Preview edit with diff → returns token |
update_card_fields_preview | Preview Q/A edit → returns token |
apply_update_card | Apply update with token |
update_cards_batch_preview | Preview batch updates |
apply_update_cards_batch | Apply batch updates |
Tag Operations (Two-Phase)
| Tool | Description |
|---|---|
add_tags_preview | Preview adding tags to cards |
remove_tags_preview | Preview removing tags |
apply_tags_update | Apply tag changes with token |
Delete Operations (Requires Confirmation)
| Tool | Description |
|---|---|
delete_card | Soft-delete (requires: "delete card <id>") |
delete_deck | Disabled by default |
Performance Notes
- Global search scans at most 1000 cards
- Per-deck search scans at most 5000 cards
- Use
list_cards_pagewith pagination for larger collections - Date filters use UTC (ISO 8601 format:
YYYY-MM-DDTHH:mm:ss.sssZ)
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
MOCHI_API_KEY | ✅ | - | Your Mochi API key |
MOCHI_ALLOW_DECK_DELETE | ❌ | false | Enable deck deletion |
MOCHI_TOKEN_EXPIRY_MINS | ❌ | 10 | Preview token validity |
Safety Design
-
Two-phase commit: Create/update operations show a preview first. You approve by using the returned token.
-
Typed confirmations: Delete requires typing
"delete card <id>"exactly. -
Deck deletion disabled: Must set
MOCHI_ALLOW_DECK_DELETE=trueto enable. -
Soft delete default: Cards go to trash (recoverable in Mochi app).
Development
# Run tests
npm test
# Type check
npm run lint
# Development mode
MOCHI_API_KEY=your_key npm run dev
# Test with MCP Inspector
npm run inspect
License
MIT