ming-metaphysics-mcp

Five Chinese metaphysics engines as MCP tools for Claude Desktop and any MCP-compatible client.

vs Cantian's bazi-mcp

Dimension	Cantian bazi-mcp	Ming ming-metaphysics-mcp
Arts covered	BaZi only	All five — BaZi + QMDJ + ZWDS + Feng Shui + I Ching
Engine depth	Good BaZi implementation	9.0–9.5/10 expert-verified across all five engines
Classical sourcing	Not documented	子平真詮, 淵海子平, 紫微斗數全書 + 108-title library cited
Output quality	Competent readings	Scholar-validated, bilingual (EN/ZH), report-grade depth
Consultation funnel	None	Master reading available via Ming Bot (link TBA)
Kua + Eight Mansions	❌	✅
QMDJ timing	❌	✅ (sxtwl Ju computation)
I Ching (Liu Yao)	❌	✅ (classical 納甲法)

---

Tools

Tool	Engine	Description
ming_bazi_analyze	BaZi 八字	Four Pillars chart — Day Master, pattern, luck pillars
ming_qmdj_direction	QMDJ 奇門	Optimal direction + timing window for a date
ming_zwds_chart	ZWDS 紫微	Twelve-palace natal chart with 四化 transformations
ming_fengshui_flying_stars	Feng Shui 風水	Kua number + Eight Mansions directional analysis
ming_iching_cast	I Ching 易經	Hexagram via classical 納甲法 (Liu Yao)
ming_full_forecast	All four birth-data engines	Integrated five-engine forecast with confidence score

---

Engine requirement

This package is an MCP wrapper. It does not contain metaphysics calculation logic — it forwards tool calls to a Ming engine endpoint over HTTP. To use it, point MING_API_URL at a running engine.

Two ways to get an engine:

1. Hosted endpoint (preferred, when available). A public Ming endpoint will be announced; once available, configure MING_API_URL to point at it and you're done.
2. Self-host. The Ming engine itself is currently a closed-source reference implementation. If you have access to the Ming codebase, run uvicorn api.main:app --port 8000 and point this MCP at localhost:8000.

Without a reachable engine, the MCP server starts and lists tools, but tool calls return an HTTP error.

Install

Step 1 — Ensure an engine is reachable

See "Engine requirement" above.

Step 2 — Install the MCP server

npm install -g ming-metaphysics-mcp

Step 3 — Add to claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ming": {
      "command": "ming-metaphysics-mcp",
      "args": [],
      "env": {
        "MING_API_URL": "http://localhost:8000"
      }
    }
  }
}

Restart Claude Desktop. The Ming tools will appear in the tools list.

Verification

In Claude Desktop:

Using the ming_bazi_analyze tool, analyze the chart for someone born 1990-03-15, male, in Singapore.

You should get a full BaZi reading. If the tool errors, verify the Python engine is running at port 8000.

---

Endpoint Gaps

The following capabilities require FastAPI expansion before they fully function as specified. Each is flagged with a note in the tool response — no silent failures.

Gap	Affected Tool	Required FastAPI Change
Annual flying star map for a specific year	ming_fengshui_flying_stars	/consult needs a year query parameter to compute annual stars for years other than current
forecast_year parameter	ming_full_forecast	/consult computes annual analysis against the current year internally; it does not accept a target year
Full ISO casting_timestamp	ming_iching_cast	/iching-cast accepts date (YYYY-MM-DD) and hour_branch separately, not an ISO 8601 timestamp; only the date portion is forwarded
goal: "bazi"/"qmdj"/"zwds" routing	All individual tools	The spec assumed /consult would accept engine-name goals, but the real endpoint uses purpose goals (wealth/career/health/relationship/general). Individual tools route to dedicated per-engine endpoints instead (/analyze, /zwds, /qmdj, /iching-cast)

To implement year-specific flying stars or forecast_year support, add those parameters to /consult in api/main.py and update the corresponding tool handlers here.

---

Development

git clone <this-repo>
cd ming-metaphysics-mcp
npm install
npm run build          # compile TypeScript → dist/
npm test               # smoke tests (no engine required)

# With engine running at localhost:8000:
npx ts-node scripts/benchmark.ts --tool all --iterations 5

Environment variables

Variable	Default	Description
MING_API_URL	http://localhost:8000	Base URL of the Ming FastAPI engine

Latency targets

Tool	Target
ming_bazi_analyze	< 3s
ming_qmdj_direction	< 3s
ming_fengshui_flying_stars	< 3s
ming_zwds_chart	< 5s
ming_full_forecast	< 5s
ming_iching_cast	< 3s

If any tool exceeds 5s consistently, check the engine bottleneck and consider adding timeout: 10000 to the MCP config.

---

Auth

None at the wrapper level — this server is open-source and free (MIT license). Authentication, if any, is enforced by whatever endpoint MING_API_URL points at.

---

For a complete five-engine reading

A guided five-engine consultation (BaZi + ZWDS + QMDJ + Feng Shui + I Ching synthesised by Master Chen) is available via Ming's Telegram bot. Link will be published once the bot is in public beta.

---

Privacy

This MCP wrapper itself does not collect data. It forwards your tool arguments (birth date, hour, gender, question text) to whichever MING_API_URL you configured. If you point at a hosted endpoint, that endpoint receives the data — read its privacy policy. If you self-host, nothing leaves your network.

Birth data is sensitive. If you're configuring this for end users, be explicit about which endpoint receives their inputs.

---

Project status

This package is at version 1.0.0. The MCP protocol surface (6 tools, JSON schemas, response shapes) is stable. The underlying Ming engine evolves faster — minor numeric changes in tool responses are normal.

Contributions welcome — see CONTRIBUTING.md.

---

License

MIT — see LICENSE.