douglasgan/asktian

CI npm License: MIT 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.

The decision layer for AI agents. Agents already plug in search, memory, and payments — askTIAN is the layer that gives them a stance: a specific, falsifiable call instead of "it depends." → Why it sells · 2-min quickstart

✨ Real readings, no key needed.

The tools call the live askTIAN backend and return real results — daily almanac, fate compatibility, name analysis, day energy — straight out of the box. The read endpoints are public and rate-limited (~300 requests / 15 min). An optional ASKTIAN_API_KEY (api.asktian.com) raises the limit and unlocks the premium tian.* reading tier. market_read is a deterministic local novelty signal; best_time returns a guided preview (no backend endpoint yet).

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 6 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.

---

API key

The key is optional — readings are real either way.

	🆓 No key (default)	🔑 With key
Setup	nothing — works instantly	get a key at api.asktian.com
Readings	real — live api.asktian.com backend (daily almanac, compatibility, name analysis, day energy)	same real readings
Rate limit	~300 requests / 15 min (per IP)	higher limits
Premium tian.* tier	—	unlocked
Cost	free	per the key's plan

To use a key (higher limits + premium tier), set ASKTIAN_API_KEY in your client config:

{
  "mcpServers": {
    "asktian": {
      "command": "npx",
      "args": ["-y", "@asktian/mcp-server"],
      "env": { "ASKTIAN_API_KEY": "at_live_..." }   // ← omit this line to stay in local mode
    }
  }
}

Hosted (streamable-HTTP)? Pass it as a header instead: Authorization: Bearer at_live_....

---

The 6 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.

6. asktian_market_read

A Chinese-metaphysics signal on a binary prediction-market question (Polymarket/Kalshi style).

input:  { question, resolve_date?: YYYY-MM-DD, subject_birthdate?: YYYY-MM-DD }
output: { signal: { lean: yes|no|neutral, score 5–95, confidence }, reasoning, disclaimer }

Use when: a user or a trading agent wants an uncorrelated, for-fun read on a market — "will X happen by date Y". The value isn't prediction; it's a deterministic signal that doesn't read the same news every LLM reads, published so the calls can be scored over time. ⚠️ Entertainment / falsifiable ritual — NOT financial advice. Every response says so, and the tool is built to be presented as a novelty, never as a bet recommendation.

---

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:

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.

---

Links

• API & docs (optional key — higher limits + premium tier): 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.

不知道就问天.