Naming
FreeNot checkedChinese name scoring for your AI agent (姓名学 / 姓名判断 / 성명학) — 五格剖象 · 三才 · 81 数理 · 生肖 · 八字喜用, computed on real 康熙笔画. Open-source MCP server. 🀄
About
Chinese name scoring for your AI agent (姓名学 / 姓名判断 / 성명학) — 五格剖象 · 三才 · 81 数理 · 生肖 · 八字喜用, computed on real 康熙笔画. Open-source MCP server. 🀄
README
🇨🇳 姓名学 (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 / 顺时.
License: MIT Powered by Shunshi.AI Node
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'sMath.rounddoes not. Scores land on.5constantly — 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
Installing Naming
This server has no published package — it is built from source. Open the repository and follow its README.
▸ github.com/shunshi-ai/naming-mcpFAQ
Is Naming MCP free?
Yes, Naming MCP is free — one-click install via Unyly at no cost.
Does Naming need an API key?
No, Naming runs without API keys or environment variables.
Is Naming hosted or self-hosted?
Self-hosted: the server runs locally on your machine via the install command above.
How do I install Naming in Claude Desktop, Claude Code or Cursor?
Open Naming on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.
Related MCPs
Opencode Omniroute Plugin
OpenCode plugin for the OmniRoute AI Gateway. Drives dynamic model discovery, /connect auth flow, and multi-instance OmniRoute providers via the official @openc
by GitHub ActionsRoblox Studio
Enables AI coding tools to control Roblox Studio for workspace exploration, instance manipulation, and script management. It provides tools for playtesting, sce
by paralovAntigravity Drawio
MCP server that enables AI assistants to create, parse, render, and validate Draw.io diagrams programmatically.
by S-SUJAN-SFetch
Web content fetching and conversion for efficient LLM usage.
AWS KB Retrieval
Retrieval from AWS Knowledge Base using Bedrock Agent Runtime.
by modelcontextprotocolSpring AI MCP Server
Provides auto-configuration for setting up an MCP server in Spring Boot applications.
llm-analysis-assistant
A very streamlined mcp client that supports calling and monitoring stdio/sse/streamableHttp, and can also view request responses through the /logs page. It also
by xuzexin-hzMCP-Agent
A simple, composable framework to build agents using Model Context Protocol by [LastMile AI](https://www.lastmileai.dev)
by lastmile-aiSpring AI MCP Client
Provides auto-configuration for MCP client functionality in Spring Boot applications.
mcp.natoma.ai
A Hosted MCP Platform to discover, install, manage and deploy MCP servers by [Natoma Labs](https://www.natoma.ai)
Compare Naming with
Not sure what to pick?
Find your stack in 60 seconds
Author?
Embed badge for your README
Browse similar
All ai MCPs
