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.

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:

Qualitative label always wins. Numbers are secondary.
Scores below 60 hide the number. Use the label only — never make someone feel rejected by a digit.
Most positive accurate framing. Same chart can be read 5 ways; pick the one that respects the person.
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:

User prompt	Tool the AI will use
"How will today be for me? Born 1992-05-15."	`asktian_daily_reading`
"I have a 3pm meeting tomorrow with a difficult client. Should I move it?"	`asktian_best_time_for_action`
"My partner is born 1990-08-22 and I'm 1992-05-15. How are we as a couple?"	`asktian_compatibility`
"What kind of day is it today?"	`asktian_today_energy`
"Is 'Aurora' a good name for my startup?"	`asktian_name_analysis`
"Best week to launch my product? My birthdate is..."	`asktian_best_time_for_action`
"Should I propose to my partner this month? Mine 1992-05-15, theirs 1990-08-22."	`asktian_best_time_for_action` + `asktian_compatibility`

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.

License

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

不知道就问天.

Keywords

mcp

model-context-protocol

FAQs

What is @asktian/mcp-server?

Is @asktian/mcp-server well maintained?

Package last updated on 31 May 2026

@asktian/mcp-server