400,000 poems, one Go binary, and a search that understands meaning
A self-hostable API for classical Chinese poetry that serves REST, GraphQL, and MCP — and can find a poem from a plain-language description.

What it does
This is a Go service wrapping roughly 400,000 classical Chinese poems and ci — Tang, Song, Yuan, plus the Shijing and Chuci — built on a typo-corrected fork of the well-known chinese-poetry dataset. It exposes the corpus three ways: a REST API with OpenAPI docs, GraphQL, and an MCP endpoint so LLM clients like Claude can query poems directly. Both simplified and traditional Chinese are stored side by side, switchable per request via a lang parameter.
The interesting bit
The optional semantic search is the headline feature: describe a scene in plain language (“snowy night, an old man fishing alone in a boat”) and it finds the matching poem by comparing query vectors against per-poem embeddings, fused with keyword search results. It’s also refreshingly honest about costs — ~350MB extra resident memory, ~30ms per query plus one embedding call, and a ~200MB vector file that must match the database release or the server refuses to load it.
Key highlights
- Full-text search via SQLite FTS5 with relevance ranking; famous anthologized poems get a scoring boost
- MCP tools are read-only, rate-limited, and address everything by name rather than unstable IDs
- Built-in IP rate limiting and multi-arch Docker images (amd64/arm64)
- Semantic search works with any OpenAI-compatible
/embeddingsendpoint, including local Ollama withbge-m3 - Runs fully self-hosted; there’s also a hosted instance if you just want to poke at it
Caveats
- Semantic search needs both the vector file and an embedding API; without them the feature simply returns 503 (REST) or an error (GraphQL)
- MCP
search_poemsis literal substring matching — your search terms must match the simplified/traditional script you selected - Building from source requires the
sqlite_fts5tag, or you’ll hitno such module: fts5
Verdict
Great fit if you build anything touching classical Chinese poetry — apps, bots, or LLM tools — and want one tidy local service instead of scraping. Skip it if you don’t read Chinese; the corpus and docs are entirely Chinese.
Frequently asked
- What is palemoky/chinese-poetry-api?
- A self-hostable API for classical Chinese poetry that serves REST, GraphQL, and MCP — and can find a poem from a plain-language description.
- Is chinese-poetry-api open source?
- Yes — palemoky/chinese-poetry-api is open source, released under the GPL-3.0 license.
- What language is chinese-poetry-api written in?
- palemoky/chinese-poetry-api is primarily written in Go.
- How popular is chinese-poetry-api?
- palemoky/chinese-poetry-api has 3.7k stars on GitHub.
- Where can I find chinese-poetry-api?
- palemoky/chinese-poetry-api is on GitHub at https://github.com/palemoky/chinese-poetry-api.