# Chengyu Coach

> Chengyu Coach is an open-source MCP server for language learning. MCP server for learning Chinese idioms (chengyu) with spaced rotation and mastery tracking. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/floweroffire/chengyu-coach-mcp
- **MCP Registry name:** io.github.FlowerOfFire/chengyu-coach-mcp
- **Categories:** [language learning](https://ai-powered.com/categories/language-learning)
- **Listing updated:** 2026-11-18

## About

The README says this server ships about 3,300 common Chinese idioms and draws them at random for daily study. It prefers idioms not yet drawn, rotates through the rest by draw count and recency, and skips recently drawn or already mastered entries by default.

Each idiom comes with its meaning, source, classical example sentences and pinyin. Progress is kept in a local SQLite file, and the connected AI client decides whether a learner has reviewed, reviewing or mastered a word and writes that status and a free-text note back through the server. The server itself does not run quizzes; the client model handles questioning and explanation.

The project suits people learning Mandarin or classical Chinese who use an MCP-capable client such as Claude Desktop, Cursor or Qoder. Data stays on the user's machine, and the word list can be replaced with another JSON file.

## Features

- **Random idiom drawing:** Draws idioms that have not been seen yet first, then rotates through the rest by draw count and recency.
- **Idiom lookup and search:** Shows meaning, source, classical examples and study progress, and searches by keyword, pinyin or pinyin initials.
- **AI-driven mastery tracking:** Lets the connected AI client set each word to learning, reviewing or mastered based on conversation performance.
- **Per-word notes:** Stores a free-form note for each idiom alongside its progress record.
- **Local progress storage:** Keeps the SQLite database on the user's machine, with the path configurable through an environment variable.
- **Replaceable word list:** Accepts a different idiom dataset in the documented JSON format.

## Good for

- Learning a few Chinese idioms each day through an AI chat client
- Reviewing idioms the learner has not yet mastered
- Checking the meaning and classical source of a specific idiom
- Tracking how many idioms have been learned and noted over time

## Install

### Claude Code (Terminal)

```sh
claude mcp add chengyu-coach-mcp -- uvx chengyu-coach-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "chengyu-coach-mcp": {
      "command": "uvx",
      "args": [
        "chengyu-coach-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "chengyu-coach-mcp": {
      "command": "uvx",
      "args": [
        "chengyu-coach-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "chengyu-coach-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "chengyu-coach-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "chengyu-coach-mcp": {
      "command": "uvx",
      "args": [
        "chengyu-coach-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "chengyu-coach-mcp": {
      "command": "uvx",
      "args": [
        "chengyu-coach-mcp"
      ]
    }
  }
}
```

## Tools

- `draw_idiom`: Randomly draws idioms, preferring ones not yet drawn.
- `idiom_detail`: Returns meaning, source, examples, progress and notes for an idiom.
- `search_idiom`: Searches the word list by keyword, pinyin or pinyin initials.
- `update_status`: Sets an idiom's status to learning, reviewing or mastered.
- `add_note`: Writes or clears a note on an idiom.
- `progress`: Summarises counts by status, noted words and recent draws.
- `reset_word`: Clears the study record for one idiom.

## FAQ

### Does the server quiz me itself?

No. The README states quizzes are decided by the client AI; the server only draws words and records progress.

### Where is my study data stored?

In a local SQLite file, by default under the home directory in .chengyu-coach, unless the CHENGYU_COACH_DB environment variable sets another path. The README says nothing is uploaded.

### How do I install it?

The README gives instructions for pip install or uvx from PyPI, plus a source install option, and a client configuration snippet using uvx.

### What license applies?

The code is MIT licensed. The idiom entries come from chinese-xinhua (MIT) and frequency data from JioNLP (Apache-2.0).

### Is Chengyu Coach free?

Yes. Chengyu Coach is open source, so you can use and self-host it for free.

### How do I add Chengyu Coach to Claude Code?

Run this command in your terminal: claude mcp add chengyu-coach-mcp -- uvx chengyu-coach-mcp

### What are the best alternatives to Chengyu Coach?

The closest alternatives to Chengyu Coach are Palabring, Langrit, Dengdeng Chinese Dictionary, Anki MCP Server and GraphChinese: Chinese dictionary and grammar.

## Where this comes from

- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Palabring](https://ai-powered.com/mcp/palabring): Palabring is an MCP server for language learning.
- [Langrit](https://ai-powered.com/mcp/langrit): Langrit is a freemium MCP server for language learning.
- [Dengdeng Chinese Dictionary](https://ai-powered.com/mcp/dengdeng-chinese-dictionary): Dengdeng Chinese Dictionary is a free MCP server for language learning.
- [Anki MCP Server](https://ai-powered.com/mcp/anki-mcp-server): Anki MCP Server is a freemium MCP server for education and exams.
- [GraphChinese: Chinese dictionary and grammar](https://ai-powered.com/mcp/graphchinese-chinese-dictionary-and-grammar): GraphChinese: Chinese dictionary and grammar is a freemium MCP server for language learning.
- [HanyuGuide](https://ai-powered.com/mcp/hanyuguide): HanyuGuide is a freemium MCP server for language learning.
- [Flashcards by Fulin Labs](https://ai-powered.com/mcp/flashcards-by-fulin-labs): Flashcards by Fulin Labs is a free MCP server for language learning.
- [Before You Speak](https://ai-powered.com/mcp/before-you-speak): Before You Speak is a freemium MCP server for language learning.

---
Source: https://ai-powered.com/mcp/chengyu-coach
