Taibu: Self-Hosted AI Platform for Traditional Chinese Divination

Fourteen Divination Systems, One Unified Platform

Taibu integrates fourteen calculation and analysis systems: Ba Zi (八字) four-pillar charting with 51 types of shen sha and true solar time correction; Zi Wei Dou Shu (紫微斗数) with flying star analysis and multi-level horoscope cycles; Liu Yao (六爻) hexagram divination with six methods of casting; Mei Hua Yi Shu (梅花易数) with body-use hexagram analysis; Qi Men Dun Jia (奇门遁甲) nine-palace charts with explicit time zone support; Da Liu Ren (大六壬) and Xiao Liu Ren (小六壬) for event divination; western Astrology with natal chart analysis; Tai Yi (太乙神数) nine-star observation; Tarot with nine spread types and 78 card interpretations; MBTI with 90-plus questions; face and palm reading via AI image recognition; compatibility analysis (合盘) for couples, business, and family; and a traditional almanac (黄历) with hourly auspice tables.

The platform stores every reading in a knowledge base that AI can reference in later conversations. Users can explicitly mention any system in a chat session, and the AI combines historical readings when generating an annual divination report.

The Ba Zi module calculates the four pillars (year, month, day, hour) using either the Gregorian or lunar calendar, applies true solar time based on birth longitude, and derives ten gods, hidden stems, twelve long-life stages, and all 51 types of shen sha (神煞) including Tian Yi Gui Ren and Jie Sha. The Zi Wei Dou Shu module fills twelve palaces with primary and auxiliary stars, computes the four transformations including self-transformation (自化), and supports multi-level cycle analysis down to the day and hour level. The Qi Men Dun Jia module uses the rotation-plate method (转盘排盘) and explicitly tracks the time zone, which matters for international users where the palace assignments shift when the local hour boundary differs from the standard Chinese hour system.

The MCP Server and the taibu-core Calculation Engine

Taibu publishes a hosted MCP server at mcp.mingai.fun/mcp that exposes all divination tools to any MCP-compatible agent. The server implements the 2026-07-28 protocol version and remains compatible with stateless clients using the 2025 specification. Configuration in any MCP client is one JSON block:

{
  "mcpServers": {
    "taibu": {
      "type": "streamable-http",
      "url": "https://mcp.mingai.fun/mcp"
    }
  }
}

No OAuth, API key, or session header is required for the public server. The README documents sixteen MCP tools including bazi, ziwei, liuyao, meihua, tarot, almanac, astrology, qimen, taiyi, daliuren, and xiaoliuren.

For developers who want the calculation engine without running the full application, the taibu-core package is published to npm under the MIT license:

npm install taibu-core

This gives access to the same calculation logic the web application uses, without the Next.js runtime, Supabase dependency, or AGPL-3.0 obligation that the main application carries.

Deploying Taibu with Docker

The repository includes three Docker Compose files. The combined deployment starts both the web application and the MCP server:

cp .env.example .env
docker compose up -d --build

The web application runs on port 3000 and the MCP server on port 3001. Separate compose files docker-compose.web.yml and docker-compose.mcp.yml are available for deploying each component on its own. The .env.example file documents all required variables: SUPABASE_URL and SUPABASE_ANON_KEY for the database, one or more LLM API keys through NEWAPI_API_KEY or OCTOPUS_API_KEY, and optionally AMAP_WEB_SERVICE_KEY for converting a birth location into longitude to calculate true solar time.

For local development, the project requires Node.js 18 or later and pnpm:

git clone [email protected]:hhszzzz/taibu.git
cd taibu
pnpm install
cp .env.example .env
pnpm dev

The development server starts at http://localhost:3000. The build step also compiles packages/core, which takes a few seconds on first run.

What the AI Integration Actually Does

The AI layer does not contain proprietary divination knowledge. It receives structured output from the calculation engines and asks a configured LLM to interpret it. The models supported depend on what API keys you supply through the NEWAPI or OCTOPUS gateway variables. The .env.example lists a fallback model field (MINGAI_FALLBACK_MODELS_JSON) that accepts a JSON array of model descriptors when the database is unavailable.

A knowledge base feature lets users store readings and reference them in later conversations using an at-mention syntax. An annual report feature aggregates all stored readings for a year into a single AI-generated summary. The README notes that AI analysis supports document attachments and web search as additional context sources.

The MBTI module runs 90-plus personality questions entirely client-side before passing the answers to the AI for narrative analysis. Face and palm reading send an uploaded image to a model that supports vision. The README does not document which specific vision models are required, only that the LLM configuration must support visual input for those two modules to work.

Where the Licensing Gets Complicated

The repository uses a mixed license. Three packages, packages/core, packages/mcp, and packages/mcp-server, are released under the MIT license. All other code in the repository, including the Next.js web application, server-side logic, and deployment configuration, is under AGPL-3.0-only.

AGPL-3.0 does not prohibit commercial use. It does require that if you deploy a modified version as a network service and others can access it, you must make the modified source available to those users under the same license. An organisation that deploys Taibu internally without modification or that runs the MCP server without modifying it does not trigger this obligation in the same way a modified public deployment would. The MIT packages carry no such requirement.

The last push to the repository was on 2026-08-01, which is about two months before this article's date. The project has no tagged GitHub releases; version tracking goes through the package.json file (version 0.1.0 for the main app) and through npm releases of taibu-core.

Limitations and What Taibu Does Not Provide

Taibu is not a self-contained calculation tool. The AI analysis requires a working LLM API connection. The full web application requires a Supabase instance for authentication, user data storage, and the vector knowledge base. Running without those services degrades most features to the calculation output alone.

The MCP server hosted at mcp.mingai.fun/mcp is a public endpoint managed by the author. If that endpoint changes or becomes unavailable, self-hosters must switch to a locally deployed MCP server using docker-compose.mcp.yml. The README documents a local stdio mode for the MCP package in packages/mcp/README.md.

The divination systems output structured astrological data according to traditional Chinese cosmological models. The platform does not make empirical claims about the predictive accuracy of any system. Users who need precise solar ephemeris or professional astronomical calculations should evaluate whether the underlying iztro and lunar-javascript libraries, which appear in the package.json dependencies, meet their precision requirements.

Editorial conclusion

Developers who want a self-hosted AI divination platform covering traditional Chinese systems such as Ba Zi and Zi Wei Dou Shu, with MCP agent integration, will find Taibu the most complete open-source option available. Those who only need the calculation engine without the full web application can use the taibu-core npm package under the MIT license without the AGPL-3.0 obligation. Before deploying the web application, verify that you have Supabase credentials, one or more LLM API keys, and optionally a Gaode (Amap) web service key for solar time calculations; without those the application boots but most AI features are inoperable.

Frequently asked questions

Official sources

1. hhszzzz/taibu on GitHub
2. Issues
3. Project website
4. README