ming-metaphysics-mcp

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

vs Cantian's bazi-mcp

Related MCP server: 命盘 Mingpan

Tools

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 @espivc/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.

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

Latency targets

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.