Shunshi Naming MCP

naming-mcp

🇨🇳 姓名学 (Chinese name numerology) ・ 🇯🇵 姓名判断 (せいめいはんだん) ・ 🇰🇷 성명학 (姓名學)

Score a Chinese name the way practitioners actually do — and give your AI agent the same ability. Open-sourced by Shunshi.AI / 顺时.

---

Two published npm packages

Package	What it is	Install
shunshi-naming-core	Pure TypeScript scoring engine. Offline, deterministic.	npm install shunshi-naming-core
shunshi-naming-mcp	Model Context Protocol server wrapping the core. For Claude Desktop / Cursor / Cline / Claude Code.	npx -y shunshi-naming-mcp

Same engine as Shunshi.AI's naming tool, parity-tested against that production backend on every release.

---

Why this exists

Ask an LLM to score a Chinese name and it will confidently produce five-grid numbers that are wrong — because 五格 is defined on 康熙笔画, not on modern stroke counts, and the two differ for exactly the characters that matter:

Character	Modern	Kangxi
万	3	15 (萬)
学	8	16 (學)
丽	7	19 (麗)

Get the stroke count wrong and every grid, the 三才 configuration, and the whole score are wrong with it. This package looks the counts up instead of guessing.

Four dimensions are scored and weighted:

Dimension	Weight	What it is
八字喜用	0.35	Do the given name's elements fall on the favourable side of the birth chart?
五格数理	0.28	The five grids (天/人/地/外/总) and their 81-number readings
生肖姓名学	0.20	Component-radical suitability for the zodiac sign
三才配置	0.17	The 天-人-地 element configuration

The 八字 and 生肖 dimensions are optional — without birth data the score renormalises over the remaining two, and says so.

Design commitments

• Everything is a lookup, nothing is a guess. No model decides a stroke count or an auspiciousness grade. Language models write prose on top of these values, never produce them.
• 三才 is a 125-entry table, not a derivation. It was once computed from the element generation/restraint rules, and that was wrong: 木金水 reads as one restraint plus one generation (半吉) by the rules, yet the tradition grades it 大凶. The table encodes centuries of accumulated judgements, not a derivable rule. Testing against reference tools put 8 of 10 sample names in a different grade before the fix.
• The zodiac layer is weighted, not vetoed. Branch relations (三合/六冲…) count double against habit rules — 「减」 for a dragon is 忌 because 辰戌六冲 outweighs "the dragon favours water", not 参半 because it happens to contain 氵. But two branch-layer hits in opposition (「翔」 for a rabbit: 羊 三合 vs 羽 卯酉冲) stay 参半, because that is a genuine stand-off and flattening it would invent certainty.
• Contested doctrine is left out. 牛忌车, 龙忌门, 鸡宜小, 蛇忌水, 鼠忌山, 猪忌辶 are all excluded. A character's own branch radical is always neutral, because the schools contradict each other outright there.

---

Quick start

Use the engine in your own app

npm install shunshi-naming-core

import { scoreName } from 'shunshi-naming-core';

const r = scoreName('顾', '学盈', {
  xiYong: ['水', '木'],   // favourable elements from the birth chart
  jiShen: ['土', '火'],   // unfavourable ones
  zodiac: '龙',
});

console.log(r.scores);          // { shuli: 56, sancai: 35, bazi: 100, zodiac: 82, total: 73 }
console.log(r.grids.ren.num);   // 37
console.log(r.sancai.combo);    // 木金土
console.log(r.bazi_match.verdict_text);
// 学（水）· 盈（水）—— 正落在喜用水、木上。命局缺的那一口气，名字替它补上了…

→ Full API reference: packages/naming-core/README.md

Give Claude / Cursor / Cline the ability to score names

{
  "mcpServers": {
    "shunshi-naming": {
      "command": "npx",
      "args": ["-y", "shunshi-naming-mcp"]
    }
  }
}

For Claude Code:

claude mcp add shunshi-naming -- npx -y shunshi-naming-mcp

Then ask:

帮我看看「顾学盈」这个名字，五格三才怎么样？

Score the name 李梓涵 — the child is a dragon and the chart favours water and wood.

「佐藤」に合う、画数のいい名前の候補を挙げて。

Pair it with shunshi-bazi-mcp and the model can compute the birth chart first, then feed the favourable elements straight into the name score.

---

Tools exposed to the model

Tool	What it does
scoreName	Full four-dimension score with per-character detail, the five grids and their readings, 三才, the three derived fortunes (基础运/成功运/社交运), and a tone analysis.
suggestNameChars	Candidate characters filtered by the stroke count or element the numerology actually needs. Returns the pool — composing the name is the model's job.
checkZodiacFit	One character judged against all twelve signs, with the triggering radicals and the reason for each.
explainShuli	What a number means in the 81-number system — grade, element, classical verse, full reading. Also accepts stroke counts and computes the grids.

---

Verification

npm install
npm run build
npm test          # 33 unit tests + 200-name cross-language parity
npm run smoke -w shunshi-naming-mcp   # end-to-end over the real MCP stdio protocol

The parity suite runs 200 names against fixtures generated by Shunshi.AI's production Python engine — 20 hand-picked to cover every structural shape (single/compound surname × single/double given name, the surname-reading overrides 任/单/区/朴, with and without birth data) plus 180 seeded-random common names. It compares the grids and their grades, the 三才 configuration, all four dimension scores and the total, the 八字 verdict including its generated prose, the per-character zodiac verdicts, the three fortunes and the tone analysis. Any divergence fails the build.

One detail worth knowing if you port this yourself: Python's round() uses banker's rounding and JavaScript's Math.round does not. Scores land on .5 constantly — a two-character zodiac score of (100+65)/2 — and the naive port disagreed with production on 63 of 200 names by exactly one point.

---

Honest limits

• Name numerology is a cultural practice, not a predictive science. These scores are for cultural understanding and entertainment. They are not advice about a person.
• 五格/三才 is Kumasaki Kenou's 1928 system (熊崎健翁, 《姓名の神秘》) — modern and Japanese in origin, not ancient Chinese. It is weighted accordingly here (45% combined) against dimensions our own engine derives.
• The 八字 dimension has only three levels (hit rate 0 / 0.5 / 1). It is the coarsest of the four yet carries the highest weight, so totals jump between a few fixed values.
• Roughly 40% of characters have no element attribution, mostly rare ones where the classical schools disagree. Those are reported as unknown rather than assigned a guess.

---

Part of the Shunshi.AI open-source ecosystem

Repo	What
bazi-reader-mcp	八字 / 四柱推命 / 사주팔자 chart engine + MCP server
kangxi-mcp	康熙字典 dictionary engine + MCP server
naming-mcp	Chinese name scoring (this repo)
zeri-mcp	择日 / date selection — weddings, moving, opening
fate-bench	Open datasets and benchmarks for Chinese metaphysics

Built by Shunshi.AI — AI-powered Chinese metaphysics, in 中文 / English / 日本語 / 한국어.

License

MIT © Shunshi.AI