← all repositories
palemoky/chinese-poetry-api

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.

chinese-poetry-api
Velocity · 7d
+6.9
★ / day
star history

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 /embeddings endpoint, including local Ollama with bge-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_poems is literal substring matching — your search terms must match the simplified/traditional script you selected
  • Building from source requires the sqlite_fts5 tag, or you’ll hit no 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.

heatdrop uses Google Analytics to see which pages get read — nothing else. Your call. How we handle data.