The asktian MCP server brings 4000 years of Chinese metaphysical traditions (八字, 奇门, 五行) into AI agents as callable tools:
Daily Personalized Reading (asktian_daily_reading): Get a personalized reading based on a birthdate, including 八卦 archetype, today's stem-branch energy, favorable colors/directions/hours, and daily advice.
Compatibility Analysis (asktian_compatibility): Compute fate compatibility between two people across dimensions (love, career, friendship, general), returning a qualitative label and optional numeric score.
Best Time for Action (asktian_best_time_for_action): Find the top 3 most auspicious time windows in the next 1–30 days for a specific action (e.g., negotiation, product launch, difficult conversation), plus times to avoid.
Today's General Energy (asktian_today_energy): Get the 干支 stem+branch and dominant five-element character for any date — no birthdate required.
Name Analysis (asktian_name_analysis): Analyze the energetic profile of any name (personal, baby, or company) using 姓名学, returning a dominant element and one-line vibe.
Market Read (asktian_market_read): Get a metaphysics-based yes/no/neutral signal on a binary prediction-market question — a deterministic, uncorrelated novelty signal for entertainment only, not financial advice.
Provides integration with LangChain via native MCP adapter, allowing LangChain agents to call asktian tools for metaphysical guidance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@asktian MCP Server When is the best time to launch my product this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 premiumtian.*reading tier.market_readis a deterministic local novelty signal;best_timereturns 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?"npm install -g @asktian/mcp-serverThen add to your client's MCP config:
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.
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"asktian": {
"command": "asktian-mcp",
"env": {
"ASKTIAN_API_KEY": "at_live_xxxxxxxxxxxxxxxx"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json — same shape as above.
Add to your Zed settings under assistant.mcp_servers — same command + env.
Run asktian-mcp as a subprocess; it speaks JSON-RPC over stdio per the MCP spec.
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.
Both have native MCP adapters — askTIAN works with zero integration code. Copy-paste snippets in docs/langchain-llamaindex.md.
Related MCP server: Prediction-Examples-in-the-Alink-Tutorial
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 | — | 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_....
asktian_daily_readingPersonalized 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 adviceUse when: user asks how today will be, what colors to wear, what direction to face their desk, daily guidance.
asktian_compatibilityFate 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".
asktian_best_time_for_actionThe 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 avoidUse 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".
asktian_today_energyGeneral energy of the day — no birthdate needed.
input: { date?: "YYYY-MM-DD" } (defaults to today)
output: 干支 stem+branch, dominant 5-element character, descriptionUse when: AI wants to add cosmic context to a generic suggestion without needing the user's birthdate.
asktian_name_analysisQuick energetic profile of a name (姓名学).
input: { name, language?: "en"|"zh"|"auto" }
output: dominant element guess, tone, one-linerUse when: discussing baby names, company names, or "what kind of person is X" when birthdate unknown.
asktian_market_readA 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.
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.
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." |
|
"I have a 3pm meeting tomorrow with a difficult client. Should I move it?" |
|
"My partner is born 1990-08-22 and I'm 1992-05-15. How are we as a couple?" |
|
"What kind of day is it today?" |
|
"Is 'Aurora' a good name for my startup?" |
|
"Best week to launch my product? My birthdate is..." |
|
"Should I propose to my partner this month? Mine 1992-05-15, theirs 1990-08-22." |
|
The agent's response in each case becomes specific and actionable instead of vague.
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.
API & docs (optional key — higher limits + premium tier): api.asktian.com
$TIAN token + wallet: wallet.asktian.com
MIT — use it anywhere, fork it, ship it inside your own product. The asktian protocol is meant to be public infrastructure.
不知道就问天.
Find the most auspicious time windows in the next N days for a specific action. Use this when the user asks 'when should I do X', 'should I move this meeting', 'is tomorrow a good day to launch', 'when should I have the hard conversation', etc. Returns top 3 best windows and any windows to avoid. This is the most useful tool for real-time decision support inside any AI assistant — it lets you give specific scheduling advice instead of vague reflections.
| Name | Required | Description | Default |
|---|---|---|---|
| birthdate | Yes | ISO YYYY-MM-DD birthdate of the person taking the action. | |
| action | No | What kind of action. Pick the closest match; use 'generic' if unsure. | |
| range_days | No | How many days ahead to search. Default 7. Max 30. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions returning top 3 best windows and windows to avoid, but does not disclose side effects, authorization needs, error handling (e.g., invalid birthdate), or any limitations. Marketing language ('most useful tool') adds no behavioral value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with purpose stated first. The final sentence ('most useful tool...') is slightly promotional but does not detract from clarity. It could be more concise by trimming that sentence, but overall it is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return format (top 3 best windows and windows to avoid) and mentions action types and range. However, it lacks details about how 'auspicious' is determined, timezone handling, or potential error cases. Given the absence of an output schema and no behavioral annotations, these gaps reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds value beyond the schema by advising to 'pick the closest match; use 'generic' if unsure' for the action parameter. This additional guidance merits a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds auspicious time windows for a specific action, with concrete examples like asking when to do something or move a meeting. It distinguishes itself from sibling tools (e.g., asktian_today_energy) by focusing on scheduling advice rather than daily readings or compatibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool: 'when the user asks 'when should I do X', 'should I move this meeting', etc.' This provides clear context. It does not mention when not to use it or alternatives, but the sibling tools cover different domains, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute fate compatibility between two people via Chinese metaphysics (八字 pairing, 5-element generation/clash). Returns qualitative label first (e.g. '互补型 Complementary'), then a numeric score (hidden if <60 to avoid making low-compat feel like rejection — this is intentional per the asktian design principles). Useful when user asks about compatibility, fit, or 'will this person and I work'.
| Name | Required | Description | Default |
|---|---|---|---|
| person_a_birthdate | Yes | ISO YYYY-MM-DD birthdate of the first person. | |
| person_b_birthdate | Yes | ISO YYYY-MM-DD birthdate of the second person. | |
| dimension | No | Which dimension to weight. Default 'general'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. Discloses key behavioral trait: numeric score is hidden if <60, with design reasoning. Also mentions methodology (八字 pairing, 5-element generation/clash). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundant details. Every sentence adds value: first states action and methodology, second states output format and behavioral nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers output format, hidden score behavior, and general purpose. However, does not explain the meaning of the 'dimension' enum values or the range of qualitative labels beyond an example. Given no output schema, slightly more detail would be ideal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; all parameters have descriptions. The tool description adds no additional parameter-level meaning beyond what schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool computes fate compatibility using Chinese metaphysics (八字, 5-element). It specifies output format: qualitative label first, numeric score second. No sibling tool overlaps, so purpose is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly indicates usefulness when user asks about compatibility, fit, or 'will this person and I work'. No explicit when-not or alternatives, but sibling tools cover different domains (e.g., market, name analysis), so context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get today's personalized Chinese metaphysics (八字 bazi + 干支 daily energy) reading for a person. Returns their archetype (one of 8 trigrams 八卦), today's energy, favorable colors/direction/hours, headline advice, and any caution. Use this when the user asks how today will be for them, what colors to wear, where to face their desk, or for general daily guidance.
| Name | Required | Description | Default |
|---|---|---|---|
| birthdate | Yes | ISO date YYYY-MM-DD (Gregorian calendar). | |
| birth_hour | No | Optional 24h time HH:MM. If unknown, omit (defaults to noon). | |
| gender | No | Optional. Some metaphysics traditions weigh gender; pass 'any' if unsure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry behavioral info. It discloses input parameters and what is returned, but does not mention if it is read-only or any side effects. Since it's a prediction tool, the behavior is implied but not explicitly stated beyond the return content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose and details, no redundancy. Every sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately lists return elements (archetype, energy, colors, direction, hours, advice, caution). All three parameters are described. However, the temporal scope ('today's') is clear from name and description, but could be explicitly reinforced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the gender parameter ('some traditions weigh gender') and birth_hour default ('defaults to noon'), which aids correct parameter specification beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides a personalized Chinese metaphysics reading for today, including specific elements like archetype, energy, colors, direction, hours, advice, and caution. This distinguishes it from siblings like asktian_best_time_for_action or asktian_compatibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instructions: 'Use this when the user asks how today will be for them, what colors to wear, where to face their desk, or for general daily guidance.' This provides clear context and implicitly tells when not to use it (e.g., for best action times or compatibility).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quick energetic profile of a name (姓名学 name-analysis). Useful when the user asks about someone's name, a baby name, a company name, or 'what kind of person is X' when no birthdate is available. Returns a one-line vibe + dominant element guess.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name to analyze. Can be in any script. | |
| language | No | Language hint. Default 'auto'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It states the output is a 'one-line vibe + dominant element guess' and implies it's quick and non-invasive. However, it doesn't disclose methodology, limitations, or whether it's based on cultural systems (e.g., Chinese numerology).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load purpose and usage. Every sentence adds value. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters, no output schema, and no annotations, the description covers purpose, usage scenarios, and output format. It is adequate, though additional context on cultural basis or limitations would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; both parameters have descriptions. The description adds that 'name' can be in any script, which is already in the schema, and does not add new meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it provides a 'quick energetic profile of a name' and lists specific use cases (baby names, company names). It differentiates from sibling tools by focusing on name analysis. However, 'energetic profile' is somewhat vague and could be more specific about what is returned (e.g., elements, traits).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit scenarios for use (when user asks about someone's name, baby name, etc.) and notes it's useful when no birthdate is available. It does not explicitly state when not to use or mention alternatives among siblings, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get today's GENERAL energy (no person needed) — the 干支 (stem + branch) and the dominant 5-element character of the day. Useful when the user asks 'what kind of day is it', 'what's the energy today', or when an AI agent wants to add cosmic context to a generic suggestion without needing the user's birthdate.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Optional ISO YYYY-MM-DD. Defaults to today (UTC). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only describes the output but does not disclose behavioral traits like read-only nature, side effects, permissions, or data freshness. For a safety-critical evaluation, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose and usage context. No redundant words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose and use cases but omits output format details (no output schema), data source (traditional Chinese calendar), and limitations. Adequate for a simple tool but with noticeable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description focuses on 'today' but the optional 'date' parameter can specify any date, creating potential confusion. It adds no extra meaning beyond the schema's parameter description, which already covers the format and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'today's GENERAL energy', and the specific output (stem+branch and dominant 5-element). It distinguishes from sibling tools by noting no person needed, making it unique among the listed tools like asktian_best_time_for_action or asktian_compatibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit use cases such as 'what kind of day is it' and when to add cosmic context without needing birthdate. It implicitly excludes personalized readings, but lacks an explicit 'when not to use' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0asktian_best_time_for_actionasktian_compatibilityasktian_daily_readingasktian_name_analysisasktian_today_energyScored across 5 tools
Each tool targets a distinct aspect of Chinese metaphysics: scheduling, compatibility, personal daily reading, name analysis, and general day energy. There is no overlap in functionality.
All tool names follow a consistent 'asktian_' prefix with descriptive snake_case names, e.g., 'asktian_best_time_for_action'. Pattern is uniform.
With 5 tools, the server is well-scoped for a niche domain like Chinese metaphysics. Each tool serves a specific purpose without redundancy.
Covers common queries like daily guidance, compatibility, name analysis, and timing. Minor gap: no explicit birth chart rendering tool, but daily_reading provides archetype and energy.
BaZi four pillars, Chinese zodiac, lunisolar calendar and almanac days for AI agents.
BaZi (八字) MCP gateway + 玄学社区. 12 tools (4 fortune + 5 forum + 3 meta). x-api-key required.
Professional Vedic astrology tools for AI agents via MCP.
Generate BaZi charts from birth details. Explore Four Pillars, solar terms, and Luck Pillars for d…
