{
  "markdown": "# asktian MCP server\n\n[![CI](https://github.com/douglasgan/asktian-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/douglasgan/asktian-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@asktian/mcp-server)](https://www.npmjs.com/package/@asktian/mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![asktian MCP server](https://glama.ai/mcp/servers/douglasgan/asktian-mcp/badges/score.svg)](https://glama.ai/mcp/servers/douglasgan/asktian-mcp)\n\n> **Chinese metaphysics inside your AI assistant.**\n> 不知道就问天 · Ask tian when you don't know.\n\nAdds 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.\n\nWhen you ask your AI assistant a timing, person, or decision question, it can quietly consult asktian before answering.\n\n**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](docs/POSITIONING.md) · [2-min quickstart](docs/quickstart.md)\n\n> ### ✨ Real readings, **no key needed.**\n>\n> The tools call the live askTIAN backend and return **real** results — daily almanac, fate\n> compatibility, name analysis, day energy — straight out of the box. The read endpoints are\n> **public and rate-limited** (~300 requests / 15 min). An **optional** `ASKTIAN_API_KEY`\n> ([api.asktian.com](https://api.asktian.com)) raises the limit and unlocks the **premium\n> `tian.*` reading tier**. `market_read` is a deterministic local novelty signal; `best_time`\n> returns a guided preview (no backend endpoint yet).\n\n```\nYou: \"I have a hard conversation with my boss tomorrow at 3pm. Should I move it?\"\n\nClaude (with asktian MCP):\n  → calls asktian_best_time_for_action({ birthdate, action: \"difficult_conversation\" })\n  → \"Friday 10am scores much higher. Tomorrow 3pm is your clash hour.\n     Want me to draft a message to reschedule?\"\n```\n\n---\n\n## Install\n\n```bash\nnpm install -g @asktian/mcp-server\n```\n\nThen add to your client's MCP config:\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"asktian\": {\n      \"command\": \"asktian-mcp\",\n      \"env\": {\n        \"ASKTIAN_API_KEY\": \"at_live_xxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Look for the 🔌 icon — asktian should appear with 6 tools.\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"asktian\": {\n      \"command\": \"asktian-mcp\",\n      \"env\": {\n        \"ASKTIAN_API_KEY\": \"at_live_xxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json` — same shape as above.\n\n### Zed\n\nAdd to your Zed settings under `assistant.mcp_servers` — same command + env.\n\n### Any other MCP client\n\nRun `asktian-mcp` as a subprocess; it speaks JSON-RPC over stdio per the [MCP spec](https://spec.modelcontextprotocol.io).\n\n### Remote / hosted (streamable-HTTP)\n\nFor LangChain, LlamaIndex, Fetch.ai, or any agent that connects to a hosted MCP endpoint,\nrun the server in HTTP mode instead of stdio:\n\n```bash\nASKTIAN_MCP_HTTP=1 PORT=8080 npx -y @asktian/mcp-server\n# → streamable-HTTP on :8080/mcp   (health check: GET :8080/health)\n```\n\nHosted at **`https://mcp.asktian.com/mcp`**. Pass your key as a Bearer header:\n`Authorization: Bearer YOUR_ASKTIAN_API_KEY`.\n\n### LangChain & LlamaIndex\n\nBoth have native MCP adapters — askTIAN works with **zero integration code**. Copy-paste\nsnippets in **[docs/langchain-llamaindex.md](docs/langchain-llamaindex.md)**.\n\n---\n\n## API key\n\n**The key is optional — readings are real either way.**\n\n| | 🆓 **No key** (default) | 🔑 **With key** |\n|---|---|---|\n| Setup | nothing — works instantly | get a key at [api.asktian.com](https://api.asktian.com) |\n| Readings | **real** — live api.asktian.com backend (daily almanac, compatibility, name analysis, day energy) | same real readings |\n| Rate limit | ~**300 requests / 15 min** (per IP) | **higher limits** |\n| Premium `tian.*` tier | — | **unlocked** |\n| Cost | **free** | per the key's plan |\n\n**To use a key** (higher limits + premium tier), set `ASKTIAN_API_KEY` in your client config:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"asktian\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@asktian/mcp-server\"],\n      \"env\": { \"ASKTIAN_API_KEY\": \"at_live_...\" }   // ← omit this line to stay in local mode\n    }\n  }\n}\n```\nHosted (streamable-HTTP)? Pass it as a header instead: `Authorization: Bearer at_live_...`.\n\n---\n\n## The 6 tools\n\n### 1. `asktian_daily_reading`\n\nPersonalized daily energy reading for a person.\n\n```\ninput:  { birthdate: \"1992-05-15\", birth_hour?: \"14:30\", gender?: \"male\"|\"female\"|\"any\" }\noutput: archetype (one of 8 trigrams), today's stem-branch energy,\n        favorable colors / direction / hours, headline + body advice\n```\n\n**Use when:** user asks how today will be, what colors to wear, what direction to face their desk, daily guidance.\n\n### 2. `asktian_compatibility`\n\nFate 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).\n\n```\ninput:  { person_a_birthdate, person_b_birthdate, dimension?: \"love\"|\"career\"|\"friend\"|\"general\" }\noutput: qualitative label, category, element flow, today's advice, score (with should_show_score flag)\n```\n\n**Use when:** \"will this person and I work\", \"compatibility check\", \"is this a good match\".\n\n### 3. `asktian_best_time_for_action`\n\nThe killer tool. Find the most auspicious time windows for a specific action over the next N days.\n\n```\ninput:  { birthdate, action: \"difficult_conversation\"|\"negotiation\"|\"launch\"|... , range_days?: 7 }\noutput: top 3 best windows (date + hour + score + reason), windows to avoid\n```\n\n**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\".\n\n### 4. `asktian_today_energy`\n\nGeneral energy of the day — no birthdate needed.\n\n```\ninput:  { date?: \"YYYY-MM-DD\" } (defaults to today)\noutput: 干支 stem+branch, dominant 5-element character, description\n```\n\n**Use when:** AI wants to add cosmic context to a generic suggestion without needing the user's birthdate.\n\n### 5. `asktian_name_analysis`\n\nQuick energetic profile of a name (姓名学).\n\n```\ninput:  { name, language?: \"en\"|\"zh\"|\"auto\" }\noutput: dominant element guess, tone, one-liner\n```\n\n**Use when:** discussing baby names, company names, or \"what kind of person is X\" when birthdate unknown.\n\n### 6. `asktian_market_read`\n\nA Chinese-metaphysics signal on a binary prediction-market question (Polymarket/Kalshi style).\n\n```\ninput:  { question, resolve_date?: YYYY-MM-DD, subject_birthdate?: YYYY-MM-DD }\noutput: { signal: { lean: yes|no|neutral, score 5–95, confidence }, reasoning, disclaimer }\n```\n\n**Use when:** a user or a trading agent wants an *uncorrelated, for-fun* read on a market —\n\"will X happen by date Y\". The value isn't prediction; it's a **deterministic signal that\ndoesn't read the same news every LLM reads**, published so the calls can be scored over time.\n⚠️ **Entertainment / falsifiable ritual — NOT financial advice.** Every response says so, and\nthe tool is built to be presented as a novelty, never as a bet recommendation.\n\n---\n\n## Design principles the tools follow\n\nasktian is opinionated. The MCP tools surface these constraints to your AI agent through the `note_for_ai` field on each response. Notable rules:\n\n1. **Qualitative label always wins.** Numbers are secondary.\n2. **Scores below 60 hide the number.** Use the label only — never make someone feel rejected by a digit.\n3. **Most positive accurate framing.** Same chart can be read 5 ways; pick the one that respects the person.\n4. **Today's advice is specific, not vague.** \"Reach out before 2pm\" beats \"Mercury retrograde.\"\n\nIf your AI client surfaces a numeric score when `should_show_score: false`, it's violating the design contract.\n\n---\n\n## Examples — sample prompts that route through asktian\n\nThese are the kinds of user prompts that an AI agent with asktian installed handles dramatically better:\n\n| User prompt | Tool the AI will use |\n|---|---|\n| *\"How will today be for me? Born 1992-05-15.\"* | `asktian_daily_reading` |\n| *\"I have a 3pm meeting tomorrow with a difficult client. Should I move it?\"* | `asktian_best_time_for_action` |\n| *\"My partner is born 1990-08-22 and I'm 1992-05-15. How are we as a couple?\"* | `asktian_compatibility` |\n| *\"What kind of day is it today?\"* | `asktian_today_energy` |\n| *\"Is 'Aurora' a good name for my startup?\"* | `asktian_name_analysis` |\n| *\"Best week to launch my product? My birthdate is...\"* | `asktian_best_time_for_action` |\n| *\"Should I propose to my partner this month? Mine 1992-05-15, theirs 1990-08-22.\"* | `asktian_best_time_for_action` + `asktian_compatibility` |\n\nThe agent's response in each case becomes specific and actionable instead of vague.\n\n---\n\n## Roadmap\n\n- [ ] Direct integration with the full api.asktian.com endpoint catalogue (qimen, ziwei, almanac, fengshui, name-analysis traditional)\n- [ ] Lucky places near me (Google Places integration)\n- [ ] Tian-points / $TIAN token incentives for power use\n- [ ] Tools for venue / business: \"is this address auspicious for a cafe\"\n- [ ] Multi-tradition cross-reference (Western astrology, Vedic, I Ching) — same person, multiple lenses\n\nPRs welcome. The lib/ folder is intentionally self-contained for clean npm distribution.\n\n---\n\n## Links\n\n- **API & docs (optional key — higher limits + premium tier):** [api.asktian.com](https://api.asktian.com)\n- **$TIAN token + wallet:** [wallet.asktian.com](https://wallet.asktian.com)\n- **Source:** [github.com/douglasgan/asktian-mcp](https://github.com/douglasgan/asktian-mcp)\n\n---\n\n## License\n\nMIT — use it anywhere, fork it, ship it inside your own product.\nThe asktian protocol is meant to be public infrastructure.\n\n不知道就问天.\n",
  "bytes": 10240,
  "sha": "f8c4f42a6203fee1a51893a5b87102a7be383758ab41de92c74eb76f04b4f3d6",
  "repo_slug": "douglasgan/asktian-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_douglasgan_asktian_f8e9a2fb/readme"
}