askTIAN MCP Server is a Chinese metaphysics decision-support tool server for AI agents, packaging traditional Chinese metaphysical systems such as Bazi, Qimen, the Five Elements, and daily ganzhi energy into AI-callable tools via the Model Context Protocol (MCP). Its positioning is to provide a "stance layer" for AI agents that already have capabilities such as search, memory, and payment—giving concrete, falsifiable judgments rather than vague answers like "it depends."
[Purpose] When a user asks an AI assistant questions about timing, people, or decisions, the AI can quietly call askTIAN to obtain metaphysical reference before answering. It is suitable for Claude Desktop, Claude Code, Cursor, Windsurf, Zed, and any MCP-compatible client.
[Main Capabilities] The server provides 6 tools:
- asktian_daily_reading: A daily energy reading for an individual, suitable for users asking about today's fortune, auspicious colors to wear, desk orientation, and other daily guidance.
- asktian_compatibility: Compatibility matching between two people. It first returns a qualitative label (such as "Complementary"), then returns a numerical score; if the score is below 60, the number is hidden to avoid making the user feel rejected.
- asktian_best_time_for_action: Finds the most auspicious time window within the next N days for a specific action. Suitable for questions such as "when should I do X," "should I reschedule the meeting," and "is tomorrow good for launching?"
- asktian_today_energy: The overall energy of the day without needing a birth date, for the AI to add macro context to general advice.
- asktian_name_analysis: A quick energy profile based on name study, suitable for discussing baby naming, company naming, or understanding "what kind of person someone is" when the birth date is unknown.
- asktian_market_read: Metaphysical signals for binary prediction market questions (Polymarket/Kalshi style). Its value lies in providing a deterministic signal that does not depend on the same news that all LLMs read, and making it public for later scoring. Note: this tool is for entertainment/falsifiable ritual purposes and is not financial advice; all responses are labeled accordingly.
[How to Use] The read endpoint is public and rate-limited (about 300 requests/15 minutes); real results can be obtained without a key.Optional configuration ASKTIAN_API_KEY (api.asktian.com) to increase limits and unlock the advanced tian.* reading tier.
Client configuration:
- Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), add the MCP configuration, then restart. The appearance of the 🔌 icon indicates that the 6 tools have loaded.
- Cursor: Edit ~/.cursor/mcp.json.
- Windsurf: Edit ~/.codeium/windsurf/mcp_config.json, in the same format as above.
- Zed: Add the same command and environment variables under assistant.mcp_servers.
- Other MCP clients: Run asktian-mcp as a subprocess and communicate via stdio using JSON-RPC.
- Remote/hosted (streamable-HTTP): For agents such as LangChain, LlamaIndex, Fetch.ai, etc. that connect to a hosted endpoint, the server can be run in HTTP mode, with the hosted address at https://mcp.asktian.com/mcp，通过 Authorization: Bearer YOUR_ASKTIAN_API_KEY header to pass the key.
- Both LangChain and LlamaIndex have native MCP adapters, usable with zero integration code; see docs/langchain-llamaindex.md for example code.
npm package: @asktian/mcp-server
[Design Principles] Tools convey constraints to AI agents through the note_for_ai field in each response: qualitative labels always take precedence over numbers; scores below 60 hide the number and use only the label, avoiding making people feel rejected by a number; the same chart has multiple ways of interpretation, choose the positive and accurate framework that most respects the person; today's advice should be specific rather than vague (e.g., "contact before 2 PM" is better than "Mercury retrograde"). If an AI client still displays a numeric score when should_show_score: false, it violates the design contract.
[Use Cases] After installing askTIAN, when an AI agent handles user questions about timing, people, or decisions, the answers become specific and actionable rather than vague.
[Limitations] market_read is a deterministic local novelty signal; best_time returns a guided preview (no backend endpoint yet). When the score is below 60, no number is displayed. market_read is for entertainment/falsifiable ritual only and does not constitute financial advice. The key is optional, but read endpoints are rate-limited.
[Future Directions] Direct integration with the full endpoint catalog of api.asktian.com (Qimen, Ziwei, Huangli, Feng Shui, traditional name analysis); nearby auspicious locations (Google Places integration); Tian-points / $TIAN token incentives; venue/business tools (e.g., "Is this address auspicious for opening a coffee shop?"); multi-tradition cross-referencing (Western astrology, Vedic, I Ching). PRs welcome; the lib/ folder is deliberately self-contained for npm distribution.
MIT license, free to use, fork, and embed in your own products.
