mcp-luopan

Turn "Luopan"—a Bazi chart calculation engine based on the Ziping Zhenquan pattern method—into an MCP (Model Context Protocol) toolset, allowing any MCP client (Claude Code / Claude Desktop / OpenClaw / Cursor / custom LLM Agent) to generate charts, read charts, and answer follow-up questions for users within a conversation.

The cloud entry point is live: https://luopan.caihangao.com. MCP points to it by default, ready to use out of the box, no need to run a local server.

What problem does it solve?

LLMs cannot calculate Bazi themselves. Letting models "analyze a chart" directly based on training knowledge is incorrect—Heavenly Stems, Earthly Branches, Monthly Commands, Ten Gods, and pattern determination are all rule-based calculations that must be performed by a specialized engine.

mcp-luopan encapsulates the entire engine (chart generation → Ten Gods → patterns → Da Yun/Luck Cycles → reports → multi-turn follow-ups) into 3 MCP tools, so the LLM no longer hallucinates, but instead:

1. Obtains accurate chart data (Four Pillars / Patterns / Da Yun / Five Elements / Ten Gods)

2. Organizes language based on real data (leaves storytelling to the LLM, facts to the engine)

3. Supports contextual follow-ups (5 follow-ups / 2-hour TTL, managed by backend session)

Related MCP server: Chinese Fortune Analysis System (BaZi)

Typical Use Cases

Scenario A: Analyzing for a friend in Claude Code / Claude Desktop

You (user):

Help me analyze a male born on March 15, 1991, at 5:00 AM, and look at his pattern and career this year.

Claude automatically:

1. Calls luopan_analyze(year=1991, month=3, day=15, hour=5, gender=1) → gets session_id and the complete chart

2. Translates "Zheng Guan Pattern / Tian Cheng / Da Yun trend / Spouse profile" into natural language for you

3. You follow up with "career this year" → Claude calls luopan_chat(session_id, "career this year") → gets an answer tailored to this specific chart

The whole process requires no knowledge of terminology or viewing JSON.

Scenario B: Batch Analysis

You want to run a "distribution of patterns for 100 celebrities":

# 伪代码：让一个 Agent 循环调用
for person in people:
    chart = call_tool("luopan_analyze", **person.birth_info)
    record(person.name, chart["pattern"]["final_pattern"])

The engine is in the cloud, not consuming your local CPU; the script only handles IO orchestration.

Scenario C: Embedding into OpenClaw / Feishu Agent

Register luopan in OpenClaw's mcp.json, authorize these 3 tools to an agent (e.g., a Feishu bot), and the agent can generate charts + answer follow-ups for users in Feishu conversations. The local OpenClaw has already run in this mode; cloud OpenClaw deployment is still TODO.

Scenario D: LLM Eval / Prompt Engineering Experiments

Want to test the language style of different models interpreting charts, or tune the "Luopan persona" for an agent—the backend always returns the same factual data, exposing model differences entirely at the natural language layer.

Quick start: 60 seconds to get started

1. Install

git clone <this-repo> /Users/Neil/Projects/mcp-servers/mcp-luopan
cd /Users/Neil/Projects/mcp-servers/mcp-luopan
uv venv && uv pip install -e .

Or use a standard venv:

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

After installation, there will be an mcp-luopan executable (in .venv/bin/).

2. Smoke test (verify without entering an MCP host)

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | .venv/bin/mcp-luopan

Expect to see 3 tools: luopan_analyze / luopan_chat / luopan_session_info.

3. Register to an MCP host

Claude Code (currently the most common)

Edit ~/.claude.json or project-level .mcp.json:

{
  "mcpServers": {
    "luopan": {
      "command": "/Users/Neil/Projects/mcp-servers/mcp-luopan/.venv/bin/mcp-luopan",
      "env": {
        "LUOPAN_API_BASE": "https://luopan.caihangao.com",
        "LUOPAN_TIMEOUT_SECONDS": "60"
      }
    }
  }
}

Restart Claude Code, then open a new session and say "Use Luopan to help me look at a chart," and it will call the tools.

OpenClaw (local or cloud)

Add to ~/.openclaw/mcp.json:

"luopan": {
  "command": "/Users/Neil/Projects/mcp-servers/mcp-luopan/.venv/bin/mcp-luopan",
  "env": {
    "LUOPAN_API_BASE": "https://luopan.caihangao.com",
    "LUOPAN_TIMEOUT_SECONDS": "60"
  }
}

To let an agent use it, the agent's tools.allow does not need to explicitly list luopan_*—OpenClaw allows all agents to see all servers in mcp.json by default.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json, with the same structure as above.

Semantics of the three tools

All tools return JSON strings. On error, they return {"error": "...", "hint": "..."}, without throwing exceptions to the LLM.

luopan_analyze(year, month, day, hour, gender)

Complete chart analysis—one call produces all information. Before calling, you must: confirm the Gregorian date, birth hour (0-23), and gender (1=male / 0=female) with the user.

Return fields (excerpt):

luopan_chat(session_id, question)

Follow-up on an existing chart. Must be within 2 hours and within 5 turns.

Return (normalized):

{
  "answer": "AI 的回答文本",
  "followup_remaining": 4,
  "followup_count": 1,
  "max_followups": 5,
  "session_id": "..."
}

When followup_remaining == 0 or session_expired is returned, you must call luopan_analyze again to start a new chart.

luopan_session_info(session_id)

Optimistic check of session status—does not hit the backend. The backend does not have an independent session status interface; authoritative determination relies on luopan_chat errors. This tool is an aid for agents to locally maintain "remembering if a session has expired."

Configuration Parameters

A complete LLM conversation example

Below is the tool call sequence the LLM should automatically generate (you only need to converse normally):

[user] 我哥 1985 年 8 月 12 日中午 12 点出生，男的，最近老换工作，帮我看看是不是格局问题？

[assistant] (调用 luopan_analyze year=1985 month=8 day=12 hour=12 gender=1)
[tool result]
  session_id=a1b2c3d4e5f6
  pattern=偏财格 / 败格有救（柳暗花明）
  ...

[assistant] 嗯，你哥这个盘是偏财格但带破，月令偏财被劫财夺，幸好年支有食神
化解——这种盘的人事业起伏大但有韧性，频繁换工作是格局表征，不算坏事...

[user] 那今年呢？

[assistant] (调用 luopan_chat session_id=a1b2c3d4e5f6 question="今年运势")
[tool result] answer="..." followup_remaining=4

[assistant] 今年走丙寅大运 + 丙午流年，火土并旺，财星受冲... (汇报答案)
你还可以追问 4 次。

The LLM will not invent astrology, all data comes from luopan_* tools; follow-ups maintain context, and each time it is based on this specific chart.

Troubleshooting

service_unreachable

Backend unreachable. Two most common causes:

• Local mode uvicorn not started—cd "/Users/Neil/Projects/Four Pillars of Destiny" && .venv/bin/uvicorn src.api.main:app --port 8000

• Cloud mode network proxy (mihomo / Clash) intercepted caihangao.com—temporarily add "HTTPS_PROXY": "" in the mcp.json env to force disable the proxy; or check the proxy rule whitelist

session_expired

Session exceeded 2h or follow-ups exhausted. Have the LLM call luopan_analyze again to start a new chart.

LLM always wants to "interpret itself" and doesn't call tools

Add a line to the System prompt:

For any questions regarding Bazi/charts/patterns/Ten Gods/Da Yun, you cannot answer based on training data; you must first call luopan_analyze to generate a chart, then use fields like pattern / report / dayun returned by the tool to organize your language.

Day Pillar/Ten Gods in the return are hard to understand

Normal—these are technical terms. Have the LLM read report.tier1 (card tier) and report.tier2 (detailed reading tier) directly; those two tiers are already Chinese narratives for humans; tier3 is the technical layer left for those willing to dig deeper.

Known Limitations

• Not published to PyPI: Must pip install -e . locally, cannot pip install mcp-luopan

• Not git-initialized: The current mcp-luopan directory does not have git init, no version management

• Session stored in memory: Backend uvicorn restart loses all sessions (user must restart the chart)

• Depends on cloud SiliconFlow: When AI_API_KEY is invalid or SiliconFlow is rate-limited, all chat tools will timeout

• No concurrency isolation: No guarantee of order when the same session_id is chatted with multiple times simultaneously

How the backend runs (Architecture Overview)

MCP Client (Claude Code / OpenClaw / ...)
   │
   │ stdio (JSON-RPC)
   ▼
mcp-luopan (Python, 这个仓库)
   │
   │ HTTPS
   ▼
luopan.caihangao.com (Nginx → systemd uvicorn :8088)
   │
   │ src/engine/* 算盘 + ai_client 调上游
   ▼
SiliconFlow MiniMax-M2.5

See the upstream project for backend service deployment details: Four Pillars of Destiny / docs/design/deployment.md.