Mochi MCP TypeScript Server

A Model Context Protocol (MCP) server that enables Claude Desktop and other MCP clients to interact with Mochi flashcard application through natural language.

Features

• 23 Tools for complete flashcard management
• 4 Learning Resources with best practices and examples
• 4 AI-Powered Prompts for flashcard generation
• Cross-platform support (Windows, macOS, Linux)
• Minimal dependencies - only uses MCP SDK and Node.js built-ins
• Rate limit compliance - Proper request serialization for Mochi API

Prerequisites

• Node.js 20.x or higher
• A Mochi account with API access
• Claude Desktop (or another MCP client)

Installation

Option 1: NPM Install (Recommended)

1. Install the package globally:

npm install -g mochi-mcp

2. Get your Mochi API key:
   • Open Mochi (web or desktop) and sign in with your Pro account (API access requires Pro)
   • Click ⚙︎ Settings in the left-hand sidebar
   • Choose Account → API Keys
   • Generate or copy the key you want to use

Option 2: Build from Source

1. Clone this repository:

git clone https://gitlab.com/sjess.hooper/mochimcp.git
cd mochimcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Get your Mochi API key:
   • Open Mochi (web or desktop) and sign in with your Pro account (API access requires Pro)
   • Click ⚙︎ Settings in the left-hand sidebar
   • Choose Account → API Keys
   • Generate or copy the key you want to use

Configuration

Environment Variables

• MOCHI_API_KEY (required): Your Mochi API key

• MOCHI_DEFAULT_DECK (optional): Default deck name (defaults to "Inbox")

• MOCHI_DEBUG (optional): Enable debug logging (set to "true")

  ⚠️ Security Warning: Debug mode logs API requests and responses. Only enable for troubleshooting and disable in production environments.

Claude Desktop Setup

1. Locate your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the Mochi server configuration:

For NPM Installation:

{
  "mcpServers": {
    "mochi": {
      "command": "mochi-mcp",
      "env": {
        "MOCHI_API_KEY": "your-api-key-here"
      }
    }
  }
}

For Source Build:

{
  "mcpServers": {
    "mochi": {
      "command": "node",
      "args": ["/absolute/path/to/mochimcp/dist/index.js"],
      "env": {
        "MOCHI_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Restart Claude Desktop

Available Tools

Core CRUD Operations

• create_flashcard - Create new flashcards with markdown content
• create_deck - Create new decks for organizing cards
• list_decks - List all available decks with metadata
• update_deck - Update deck properties
• delete_deck - Delete decks and contained cards
• get_card - Get full details of a specific card
• update_card - Update card content and properties
• delete_card - Delete individual cards
• move_cards - Move multiple cards between decks

Search and Query

• search_cards - Search cards by content
• list_cards - List cards with filtering options
• get_deck_by_name - Find deck by name
• get_cards_due_for_review - Get cards ready for review
• find_similar_cards - Find related cards

Bulk Operations

• bulk_create_cards - Create multiple cards at once
• add_tags_to_cards - Add tags to multiple cards
• remove_tags_from_cards - Remove tags from cards

Templates

• list_templates - List available card templates
• get_template - Get template details
• create_card_from_template - Create cards using templates

Import/Export

• import_from_markdown - Import cards from markdown format
• export_deck - Export deck to various formats

Tag Management

• list_tags - List all available tags

Available Resources

Access learning resources using their URIs:

• flashcard://best-practices - Comprehensive flashcard creation guide
• flashcard://examples/programming - Programming flashcard examples
• flashcard://examples/languages - Language learning examples
• flashcard://cloze-guide - Cloze deletion guide

Available Prompts

AI-powered prompts for flashcard generation:

• create_cards_from_conversation - Extract learning points from conversation
• generate_flashcards_from_text - Convert study material to cards
• improve_flashcard - Get suggestions for card improvement
• create_cloze_cards - Generate cloze deletion cards

Usage Examples

Once configured in Claude Desktop, you can use natural language commands:

• "List my Mochi decks"
• "Create a flashcard about Python list comprehensions"
• "Search for cards about JavaScript"
• "Show me cards due for review"
• "Import flashcards from this markdown text"
• "Create cloze deletion cards about photosynthesis"

Development

Running in Development Mode

# Set environment variables
export MOCHI_API_KEY="your-api-key"
export MOCHI_DEBUG="true"

# Run the server
npm start

Testing

Test the server directly:

# List tools
echo '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}' | npm start

Project Structure

mochimcp/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server implementation
│   ├── mochi-client.ts    # Mochi API client
│   ├── config.ts          # Configuration management
│   ├── logger.ts          # Debug logging
│   ├── tools/             # Tool implementations
│   ├── resources/         # MCP resources
│   ├── prompts/           # MCP prompts
│   └── types/             # TypeScript types
├── dist/                  # Compiled JavaScript
└── package.json

Troubleshooting

Server doesn't appear in Claude

1. Check Claude Desktop logs (Help → Show Logs)
2. Verify the path to index.js is absolute
3. Ensure the API key is valid
4. Make sure you've built the project (npm run build)

Authentication errors

• Verify you have a Mochi Pro account (API access requires Pro subscription)
• Double-check your API key in Mochi: Settings → Account → API Keys
• Ensure no extra spaces in the API key
• Confirm the API key is active and not expired

API errors

• The server includes retry logic for temporary failures
• Check debug logs by setting MOCHI_DEBUG=true
• Verify your Mochi account has API access enabled

Rate Limiting

The Mochi API enforces a strict one request at a time rate limit. This MCP server handles this automatically by:

• Queuing all API requests to ensure sequential execution
• Serializing tool invocations at the server level
• Monitoring and logging request patterns

You should never see HTTP 429 (rate limit) errors during normal operation. If you do, please report it as a bug.

Security Best Practices

API Key Management

• Never commit your API key to version control
• Store your API key securely in Claude Desktop's configuration
• Rotate your API key regularly from Mochi's settings

Debug Mode

• Disable debug mode in production (MOCHI_DEBUG=false or omit the variable)
• Debug logs may contain sensitive information from API requests/responses
• Only enable debug mode for troubleshooting specific issues

Environment Variables

• Use environment variables for all sensitive configuration
• Avoid hardcoding API keys or other secrets in scripts

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a merge request

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with the Model Context Protocol SDK
• Inspired by the original Swift implementation
• Thanks to the Mochi team for their excellent API