# OpenCidian by Perxel

> An open Chinese-Vietnamese dictionary, served to AI assistants over MCP. Hán Việt, pinyin and Vietnamese meaning for every word, and every field says which source it came from. Free, no sign-in; read-only except suggest_correction, which opens a public issue for review.

OpenCidian joins CC-CEDICT (Chinese-English), CVDICT (Chinese-Vietnamese), Thiều Chửu's Hán Việt tự điển, Unihan, Make Me a Hanzi and the HSK word lists into one dataset of about 125,000 words and 14,500 characters, each source pinned to a version. Questions can be asked in Vietnamese or English.

There is no public REST API: for assistants and other systems, the MCP server is the way in.

## Connect

MCP server (Streamable HTTP, no auth): https://opencidian-mcp.perxel.com/mcp

- Claude (claude.ai, Desktop, mobile): Settings → Connectors → Add custom connector → paste the URL.
- Claude Code: `claude mcp add --transport http opencidian https://opencidian-mcp.perxel.com/mcp`
- ChatGPT: Settings → Apps & Connectors → Advanced settings → turn on Developer mode → Create, then paste the URL (no authentication).
- Cursor, VS Code and other clients with an `mcp.json`: `{ "mcpServers": { "opencidian": { "url": "https://opencidian-mcp.perxel.com/mcp" } } }`
- Clients that only speak stdio: `npx mcp-remote https://opencidian-mcp.perxel.com/mcp`

## Try asking

- 觉得 nghĩa là gì? Âm Hán Việt là gì?
- "Cảm thấy" tiếng Trung nói thế nào?
- Chữ 觉 có những âm Hán Việt nào, gồm những bộ phận gì?
- Những từ thông dụng nào có chữ 觉?
- Phiên âm và nghĩa từng từ trong câu: 他觉得北京很好。
- Where does OpenCidian's data come from, and how do I cite it?

## Tools

- `lookup`: Dictionary entries for a Chinese word, a pinyin syllable or a Vietnamese word: simplified and traditional forms, pinyin, Hán Việt per character (Thiều Chửu), Vietnamese senses (CVDICT), English senses (CC-CEDICT), HSK level.
- `get_character`: Everything known about one character: Hán Việt readings (Thiều Chửu first, Unihan when Thiều Chửu has none), pinyin readings, a short English gloss, stroke count, radical, its parts (decomposition) and how it was formed (etymology: the meaning part and the sound part, each with its Hán Việt), and its traditional or simplified forms.
- `words_with`: Words of two characters or more that contain a character (simplified or traditional), HSK words first, then shorter words.
- `search_meaning`: Vietnamese or English → Chinese: entries whose Vietnamese (CVDICT) or English (CC-CEDICT) senses match the meaning, HSK words first.
- `annotate_text`: Splits Chinese text into words (longest match against the dictionary) and gives each its pinyin, Hán Việt per character, Vietnamese and English senses and entry `id`.
- `suggest_correction`: Sends a correction for a wrong or missing value (Hán Việt, Vietnamese meaning, English, pinyin, a missing word) as a public GitHub issue in OpenCidian/opencidian-data; a maintainer reviews it, nothing changes in the data until then.
- `about`: The dataset's version and build date, its licence (CC BY-SA 4.0), the full attribution to quote when reusing it, and every source with its pinned version and licence (CC-CEDICT, CVDICT, Thiều Chửu, Unihan, Make Me a Hanzi, the HSK lists).

## Prompts

Templates you pick in the client (a slash command, or the "+" menu in Claude) instead of typing the request:

- `word-analysis`: Analyses a Chinese character, word or idiom for Vietnamese learners, in Vietnamese: pinyin, Hán Việt, meaning, stroke count, parts and origin, lục thư type, related words, usage notes and 5 examples.

## Trust

- Every field carries `src`: the source it came from, or a correction.
- Every answer carries the dataset version.
- A word the dictionary doesn't have is reported as missing, never guessed.

## License and attribution

The data is CC BY-SA 4.0: credit "OpenCidian by Perxel" and its sources (the `about` tool gives the full credit), link to https://opencidian-mcp.perxel.com, and share changes under the same licence. The code is MIT.

## Links

- Docs page and tool list: https://opencidian-mcp.perxel.com/
- Usage dashboard: https://opencidian-mcp.perxel.com/dash
- Perxel: https://perxel.com
- Contact: https://github.com/OpenCidian