# Mochi MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io/) server that enables AI agents (Claude, Codex, etc.) to manage your [Mochi.cards](https://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
```bash
# 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`:
```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_page` with 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
1. **Two-phase commit**: Create/update operations show a preview first. You approve by using the returned token.
2. **Typed confirmations**: Delete requires typing `"delete card <id>"` exactly.
3. **Deck deletion disabled**: Must set `MOCHI_ALLOW_DECK_DELETE=true` to enable.
4. **Soft delete default**: Cards go to trash (recoverable in Mochi app).
## Development
```bash
# 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
