Cantonese Dictionary MCP Server

An MCP (Model Context Protocol) server that provides Cantonese dictionary lookup functionality using data from the Open Cantonese Dictionary (開放粵語字典).

Features

• Look up Chinese characters for Cantonese pronunciation (Jyutping)
• Search by pronunciation, tone, or definition
• Get pronunciations for phrases and sentences
• 6,500+ character entries with definitions and examples

Installation

Prerequisites

• Node.js 18 or higher
• npm

Setup

1. Clone or download this repository:

git clone https://github.com/NewJerseyStyle/cant-dict-mcp.git
cd cant-dict-mcp

2. Install dependencies:

npm install

3. Download the dictionary data:

npm run download-data

4. Build the project:

npm run build

Configuration

Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "cantonese-dictionary": {
      "command": "npx",
      "args": ["cant-dict-mcp"]
    }
  }
}

Available Tools

lookup_character

Look up a Chinese character in the Cantonese dictionary.

Parameters:

• character (string, required): The Chinese character to look up (traditional or simplified)

Example:

Input: 講
Output:
  字 Character: 講 (简: 讲)
  拼音 Jyutping: gong2
  釋義 Definition: ...

search_by_jyutping

Search for characters by their Cantonese pronunciation (Jyutping).

Parameters:

• jyutping (string, required): The Jyutping pronunciation (e.g., "gong2", "sik1")
• exact (boolean, optional): If true, only exact matches. Default: false

Example:

Input: sik1
Output: 識, 式, 息, 熄, ...

search_definition

Search for characters by keywords in their definition.

Parameters:

• query (string, required): The search term (in Chinese)

Example:

Input: 語氣
Output: Characters with definitions containing "語氣"

search_by_tone

Find all characters with a specific Cantonese tone.

Parameters:

• tone (number, required): The tone number (1-6)
• initial (string, optional): Filter by initial consonant (e.g., "g", "s", "ng")

Cantonese Tones: | Tone | Name | Example | |------|------|---------| | 1 | 陰平 (high level) | 詩 si1 | | 2 | 陰上 (high rising) | 史 si2 | | 3 | 陰去 (mid level) | 試 si3 | | 4 | 陽平 (low falling) | 時 si4 | | 5 | 陽上 (low rising) | 市 si5 | | 6 | 陽去 (low level) | 事 si6 |

lookup_phrase

Look up pronunciation for each character in a phrase or sentence.

Parameters:

• phrase (string, required): The Chinese phrase or sentence

Example:

Input: 你好
Output:
  你: nei5
  好: hou2 / hou3

dictionary_stats

Get statistics about the Cantonese dictionary.

Parameters: None

Output: Total entries, unique characters, tone distribution, etc.

Development

Run in development mode:

npm run dev

Build for production:

npm run build

Data Source & Acknowledgments

This project uses data from the Open Cantonese Dictionary (開放粵語字典).

• Repository: https://github.com/kfcd/yyzd
• Maintainer: Open Dictionary (開放詞典)
• Romanization: Jyutping (粵拼)

License

The dictionary data is licensed under Creative Commons Attribution 3.0 Unported (CC BY 3.0).

When using this data, please provide attribution:

Data from Open Cantonese Dictionary (開放粵語字典) by Open Dictionary, 2009-2020. Licensed under CC BY 3.0. https://github.com/kfcd/yyzd

The MCP server code in this repository is licensed under MIT.

About Jyutping

Jyutping (粵拼) is the standard Cantonese romanization system developed by the Linguistic Society of Hong Kong. It uses:

• Initials: b, p, m, f, d, t, n, l, g, k, ng, h, gw, kw, w, z, c, s, j
• Finals: aa, aai, aau, aam, aan, aang, aap, aat, aak, ai, au, am, an, ang, ap, at, ak, e, ei, eu, em, eng, ep, ek, i, iu, im, in, ing, ip, it, ik, o, oi, ou, on, ong, ot, ok, u, ui, un, ung, ut, uk, oe, oeng, oek, eoi, eon, eot, yu, yun, yut, m, ng
• Tones: 1-6 (written as numbers after the syllable)

Troubleshooting

"Dictionary data not found"

Run the download script:

npm run download-data

Server not responding

Ensure you've built the project:

npm run build

Check that the path in your MCP configuration is correct and absolute.