asktian MCP server

Chinese metaphysics inside your AI assistant. 不知道就问天 · Ask tian when you don't know.

Adds 4000 years of Chinese metaphysical traditions (bazi / 八字, qimen / 奇门, five elements, daily 干支 energy) as callable tools for any AI agent that speaks the Model Context Protocol — Claude Desktop, Claude Code, Cursor, Windsurf, Zed, and any MCP-compatible client.

When you ask your AI assistant a timing, person, or decision question, it can quietly consult asktian before answering.

You: "I have a hard conversation with my boss tomorrow at 3pm. Should I move it?"

Claude (with asktian MCP):
  → calls asktian_best_time_for_action({ birthdate, action: "difficult_conversation" })
  → "Friday 10am scores much higher. Tomorrow 3pm is your clash hour.
     Want me to draft a message to reschedule?"

Install

npm install -g @asktian/mcp-server

Then add to your client's MCP config:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "asktian": {
      "command": "asktian-mcp",
      "env": {
        "ASKTIAN_API_KEY": "at_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. Look for the 🔌 icon — asktian should appear with 5 tools.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "asktian": {
      "command": "asktian-mcp",
      "env": {
        "ASKTIAN_API_KEY": "at_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json — same shape as above.

Zed

Add to your Zed settings under assistant.mcp_servers — same command + env.

Any other MCP client

Run asktian-mcp as a subprocess; it speaks JSON-RPC over stdio per the MCP spec.

Remote / hosted (streamable-HTTP)

For LangChain, LlamaIndex, Fetch.ai, or any agent that connects to a hosted MCP endpoint, run the server in HTTP mode instead of stdio:

ASKTIAN_MCP_HTTP=1 PORT=8080 npx -y @asktian/mcp-server
# → streamable-HTTP on :8080/mcp   (health check: GET :8080/health)

Hosted at https://mcp.asktian.com/mcp. Pass your key as a Bearer header: Authorization: Bearer YOUR_ASKTIAN_API_KEY.

LangChain & LlamaIndex

Both have native MCP adapters — askTIAN works with zero integration code. Copy-paste snippets in docs/langchain-llamaindex.md.

Related MCP server: ming-metaphysics-mcp

API key

The server works without an API key — it falls back to local logic so you can try it instantly.

For higher-quality readings (real bazi computation from api.asktian.com's 70+ endpoints, daily fortune, compatibility scoring against the full system), get a free key at api.asktian.com and set ASKTIAN_API_KEY in your client config.

The 5 tools

1. asktian_daily_reading

Personalized daily energy reading for a person.

input:  { birthdate: "1992-05-15", birth_hour?: "14:30", gender?: "male"|"female"|"any" }
output: archetype (one of 8 trigrams), today's stem-branch energy,
        favorable colors / direction / hours, headline + body advice

Use when: user asks how today will be, what colors to wear, what direction to face their desk, daily guidance.

2. asktian_compatibility

Fate compatibility between two people. Returns qualitative label first (e.g. "互补型 Complementary"), then numeric score (hidden if <60 per asktian design principles — low compat should never feel like rejection).

input:  { person_a_birthdate, person_b_birthdate, dimension?: "love"|"career"|"friend"|"general" }
output: qualitative label, category, element flow, today's advice, score (with should_show_score flag)

Use when: "will this person and I work", "compatibility check", "is this a good match".

3. asktian_best_time_for_action

The killer tool. Find the most auspicious time windows for a specific action over the next N days.

input:  { birthdate, action: "difficult_conversation"|"negotiation"|"launch"|... , range_days?: 7 }
output: top 3 best windows (date + hour + score + reason), windows to avoid

Use when: "when should I do X", "should I move this meeting", "is tomorrow a good day to launch", "when should I have the hard talk".

4. asktian_today_energy

General energy of the day — no birthdate needed.

input:  { date?: "YYYY-MM-DD" } (defaults to today)
output: 干支 stem+branch, dominant 5-element character, description

Use when: AI wants to add cosmic context to a generic suggestion without needing the user's birthdate.

5. asktian_name_analysis

Quick energetic profile of a name (姓名学).

input:  { name, language?: "en"|"zh"|"auto" }
output: dominant element guess, tone, one-liner

Use when: discussing baby names, company names, or "what kind of person is X" when birthdate unknown.

Design principles the tools follow

asktian is opinionated. The MCP tools surface these constraints to your AI agent through the note_for_ai field on each response. Notable rules:

1. Qualitative label always wins. Numbers are secondary.

2. Scores below 60 hide the number. Use the label only — never make someone feel rejected by a digit.

3. Most positive accurate framing. Same chart can be read 5 ways; pick the one that respects the person.

4. Today's advice is specific, not vague. "Reach out before 2pm" beats "Mercury retrograde."

If your AI client surfaces a numeric score when should_show_score: false, it's violating the design contract.

Examples — sample prompts that route through asktian

These are the kinds of user prompts that an AI agent with asktian installed handles dramatically better:

The agent's response in each case becomes specific and actionable instead of vague.

Roadmap

• Direct integration with the full api.asktian.com endpoint catalogue (qimen, ziwei, almanac, fengshui, name-analysis traditional)

• Lucky places near me (Google Places integration)

• Tian-points / $TIAN token incentives for power use

• Tools for venue / business: "is this address auspicious for a cafe"

• Multi-tradition cross-reference (Western astrology, Vedic, I Ching) — same person, multiple lenses

PRs welcome. The lib/ folder is intentionally self-contained for clean npm distribution.

Links

• Web app: play.asktian.com (coming soon)

• API + free key: api.asktian.com

• $TIAN token + wallet: wallet.asktian.com

• Source: github.com/douglasgan/asktian-mcp

License

MIT — use it anywhere, fork it, ship it inside your own product. The asktian protocol is meant to be public infrastructure.

不知道就问天.