Mochi

You run a Mochi Context Protocol (MCP) server that lets AI agents manage your Mochi.cards flashcards. It provides safe, two-phase commit style create/update actions, fast read operations, and configurable safety settings so you control what can be deleted or modified.

How to use

You connect an MCP client to your Mochi MCP server to browse decks, search cards, create and update cards with a preview step, and delete cards with typed confirmation for safety. Use the server locally or via an MCP client that supports stdio connections. Start with your API key and the standard run flow, then interact with the client to perform actions like listing decks, searching cards, or applying approved changes.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

# Install dependencies
npm install

# Build the project
npm run build

# Run the server (needs your Mochi API key)
MOCHI_API_KEY=your_key_here node dist/index.js

Configuration and usage notes

Configure how you run the server and how you connect clients. The API key must be provided to authorize requests to Mochi. You can enable or disable deck deletion with an environment variable, and you can set how long preview tokens remain valid.

Example configuration you can use with Claude Desktop for direct interaction shows how to point Claude to the local MCP server and supply your API key.

{
  "mcpServers": {
    "mochi": {
      "command": "node",
      "args": ["/path/to/mochi-mcp/dist/index.js"],
      "env": {
        "MOCHI_API_KEY": "your_api_key"
      }
    }
  }
}

Claude Desktop example

Add Mochi MCP to Claude Desktop by configuring the standard stdio connection, then ask Claude to list decks or search cards.

{
  "mcpServers": {
    "mochi": {
      "command": "node",
      "args": ["/path/to/mochi-mcp/dist/index.js"],
      "env": {
        "MOCHI_API_KEY": "your_api_key"
      }
    }
  }
}

Safety and usage notes

Two-phase commit is used for create and update operations. You preview changes first and must approve them with the token returned by the preview step. Deletion of decks is disabled by default and requires explicit enabling. Deleting cards requires a typed confirmation: you must provide the exact string "delete card <id>" to proceed. Soft deletion places cards in the Mochi trash, from which you can recover them.

Performance considerations

Global search scans up to 1000 cards, and per-deck search scans up to 5000 cards. For large collections, use paginated listing via the provided paging tool to avoid long searches. Date filters use UTC ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ.

Security and configuration

Key environment variables:

• MOCHI_API_KEY: Your Mochi API key (required)
• MOCHI_ALLOW_DECK_DELETE: Enable deck deletion (default false)
• MOCHI_TOKEN_EXPIRY_MINS: Preview token validity in minutes (default 10)

Development and testing

Common development commands you can use while building or validating the MCP server locally.

# Run tests
npm test

# Type check / lint
npm run lint

# Development mode (provide your API key)
MOCHI_API_KEY=your_key npm run dev

# Inspect MCP interactions
npm run inspect

Available tools

list_decks

List all decks available in Mochi.cards.

get_deck

Retrieve a specific deck and its card list.

get_card

Fetch the full content of a single card.

get_cards

Retrieve multiple cards by their IDs.

search_cards

Search cards by text, tags, or date; returns rich results including deckId and createdAt.

list_cards_page

Provide a paginated listing of cards with bookmarking support.

find_deck_by_name

Find decks by name using case-insensitive partial matching.

create_card_preview

Preview a new card and receive a token for later application.

apply_create_card

Apply the creation of a card using the provided token.

update_card_preview

Preview edits to a card and receive a token for later application.

update_card_fields_preview

Preview updates to question/answer fields and receive a token for later application.

apply_update_card

Apply updates to a card using the provided token.

update_cards_batch_preview

Preview a batch of card updates and receive a token for later application.

apply_update_cards_batch

Apply batch updates using the provided token.

add_tags_preview

Preview adding tags to selected cards and receive a token for later application.

remove_tags_preview

Preview removing tags from selected cards and receive a token for later application.

apply_tags_update

Apply tag changes to cards using the provided token.

delete_card

Soft-delete a card after confirming with the exact instruction "delete card <id>".

delete_deck

Delete a deck (disabled by default in safe mode).