Tu Vi Horoscope MCP Server

This is a Model Context Protocol (MCP) server developed in Python that calculates and manages Vietnamese "Tử Vi" horoscope charts. It is optimized to output clean, structured JSON data that LLM agents can easily read, interpret, and explain to users.

English Documentation

Quick Links

• Full Documentation
• Contributing Guidelines
• Changelog / Release History
• Example JSON Outputs & Scripts

Features

• Horoscope Generation: Converts Solar or Lunar birth dates and times into a full Tử Vi chart (Thiên Bàn and Địa Bàn with 12 houses and over 100 stars).
• 51 Cách Cục Evaluation Engine: Automatically recognizes all 51 traditional astrological formations (51 Cách Cục Trung Châu Phái) during chart generation, returning matched patterns with descriptions, poems (Cổ Ca), commentary (Bình Chú), and pros/cons (Ưu/Khuyết điểm).
• High-Quality Image Rendering: Generates beautiful, print-ready chart images with element-based colored text (Green for Wood, Red for Fire, Yellow for Earth, Gray for Metal, Blue for Water), custom badge boxes for Tuần & Triệt, and geometric connecting lines highlighting the Mệnh and Thân relationship.
• Vận Hạn (Transit Analysis): Computes transit stars (Lưu tinh) and maps the active 10-year period (Đại Hạn), yearly period (Tiểu Hạn), monthly period (Nguyệt Hạn), and daily period (Nhật Hạn) for any target year, month, and day (e.g., 2026).
• Auspicious Date & Time Checker: Evaluates Hoàng Đạo/Hắc Đạo, 12 Trực, 28 Tú, Tiết Khí, travel directions, and auspicious hours for any calendar date.
• Local Persistence (Python Library): Includes built-in SQLite database utilities (tuvi_mcp.database) for Python library consumers to save, retrieve, list, and delete horoscope profiles. (MCP tools are stateless and do not require a database.)
• Flexible Hour Mapping: Automatically maps calendar hours (e.g., "14:30") or string names (e.g., "Ngọ", "Tý") to the correct Earthly Branch hour index.
• Local Inlining (Independent): Includes the core ansaotuvi calculation logic internally with custom Tuần/Triệt double-cung fixes.

Python Library API

Beyond the MCP server, tuvi-mcp-server ships a typed, ergonomic Python API for direct use in scripts, notebooks, or web backends:

from tuvi_mcp import Horoscope, BirthInfo, Gender, Calendar

# Construct a horoscope handle from birth details (flexible hour / gender / calendar inputs)
h = Horoscope.from_birth(
    name="Nguyễn Văn A",
    year=1995, month=6, day=10,
    hour="14:30",          # also accepts "Ngọ", 14, or 7 (branch index)
    gender="Nam",          # also accepts "male", 1, True, or Gender.MALE
    calendar="solar",      # also accepts Calendar.SOLAR
)

# Base birth chart
chart = h.chart()
print(chart.thien_ban["can_nam"], chart.thien_ban["chi_nam"])
print(len(chart.dia_ban), "cungs")

# Vận Hạn for a target Lunar year/month/day
van_han = h.transit(year=2026, month=5, day=15)
print(van_han["target_period"]["current_year_can_chi"])
print(van_han["nhat_han"])

# Auspicious day evaluation
auspicious = h.auspicious(day=27, month=7, year=2026)

# Render chart as PNG (uses bundled Roboto Unicode font by default)
path = h.render_chart(chart, year=2026)

# Optionally specify custom TTF font files
path = h.render_chart(chart, year=2026, font_path="/path/to/custom_font.ttf")

The same library is what the MCP tools wrap, so behavior is identical whether you call Horoscope.from_birth(...).chart() or invoke the generate_horoscope tool from an MCP client.

from tuvi_mcp import AuspiciousResult, TransitResult

# All results support attribute access + to_dict() for JSON serialization
chart = h.chart()
print(chart.thien_ban["can_nam"], chart.thien_ban["chi_nam"])
json_data = chart.to_dict()  # ← JSON-serializable dict

# Transit (Vận Hạn) and Auspicious results are also typed objects
van_han: TransitResult = h.transit(year=2026, month=5)
auspicious: AuspiciousResult = h.auspicious(day=27, month=7, year=2026)

# SQLite database — save, list, retrieve profiles
from tuvi_mcp.database import init_db, save_horoscope, list_saved_horoscopes, get_saved_horoscope_by_name

init_db()  # one-time setup
id_ = save_horoscope("My Chart", 10, 6, 1995, 14, "Nam", True)
print(f"saved as id {id_}")
profiles = list_saved_horoscopes()
print(profiles)  # [{"id": 1, "name": "My Chart", ...}]

Known Limitations & Assumptions

• Timezone: Calculations default to the Vietnamese local timezone (GMT+7). For births elsewhere, pass timezone explicitly to the MCP tool (timezone accepts an integer like 8 or an h:30 string like "8:30"). Defaults to 7 when omitted. The astronomical engine uses the supplied timezone only for boundary rounding of the Solar↔Lunar date — the civil hour branch (chi giờ) is always derived from the user-supplied local clock time.
• Calendar Boundaries: The core calculations are stable for modern birth years, but traditional leap months (tháng nhuận) follow standard Vietnamese lunar calendar mappings (Hoang Nam Dia methodology) which might vary in historical or remote future years.
• Calculations School (Phái): Star distributions follow standard consensus calculations. Customizable star weight/distributions (different schools like Nam Phái vs. Bắc Phái vs. custom configurations) are not supported.

Accuracy, Methodology & Tradition Disclaimer

[!NOTE] Traditional Calculations Disclaimer: Vietnamese "Tử Vi" is a highly rich astrological methodology with various traditional schools (e.g., Nam Phái vs. Bắc Phái). Calculation parameters, star rankings, element determinations, and interpretations may differ depending on the specific lineage or school. The output generated by this tool is calculated strictly according to standard consensus computational logic and should be treated as a computational reference rather than a definitive astrological interpretation.

Installation

You can install tuvi-mcp-server directly from PyPI:

pip install tuvi-mcp-server

Development & Contribution Setup

If you want to contribute to the package or run unit tests, set up a local development environment:

1. Create Virtual Environment:

   bash

   Copy

   python3 -m venv .venv
   

2. Install Package in Editable Mode:

   bash

   Copy

   .venv/bin/pip install --upgrade pip
   .venv/bin/pip install -e ".[test]"
   

3. Running Tests: Verify your local setup by running the test suite:

   bash

   Copy

   .venv/bin/pytest
   

How to Run

1. Stdio Mode (Default for Claude Desktop & Cursor)

.venv/bin/tuvi-mcp

2. Streamable HTTP Mode (For Remote & Cloud Deployments)

To run the server over HTTP (runs on port 1850 by default):

.venv/bin/tuvi-mcp --http

Override host and port:

.venv/bin/tuvi-mcp --http --host 127.0.0.1 --port 1850

Tool API Reference

All tools run locally inside the MCP environment. They require no external authentication or network rate limiting.

1. generate_horoscope

Generates a full Tử Vi chart from raw birth details, with optional high-quality chart image rendering.

• Purpose & Comparison: Use this tool to compute and inspect an astrological birth chart from scratch for arbitrary birth details.
• Side Effects: If generate_image is True, renders a PNG file to a temporary location on the local filesystem and returns its path.
• Arguments:
  • name (string): Person's name (default: "Khách").
  • day (integer): Day of birth (1-31).
  • month (integer): Month of birth (1-12).
  • year (integer): Year of birth.
  • hour_val (string): Hour of birth (e.g., "14:30", "Ngọ", "Tý", or branch index 1-12). Interpreted as local civil time at the birthplace — do not convert to Vietnam time unless that is the intended civil-tz reference (see timezone below).
  • gender_val (string): Gender ("Nam" or "Nữ", case-insensitive).
  • is_solar (boolean): True for Solar, False for Lunar (default: True).
  • current_year (integer, optional): Year to inspect transit stars/Vận Hạn for (defaults to current year).
  • generate_image (boolean, optional): Whether to generate and return the high-quality chart image along with the chart data (default: True).
  • timezone (integer or string, optional): UTC offset for the civil timezone at the birthplace. Accepts an integer (e.g. 7, -5) or an h:30 string (e.g. "7:30", "-5:30"). Default: 7 (ICT/Vietnam). Other minute values and out-of-range inputs are rejected. Only the boundary rounding of astronomical events (lunar day, tiết-khí, Đông chí) is affected — the civil hour branch (chi giờ) is always derived from hour_val.
• Return Value:
  • If generate_image is True, returns a list containing [Image, chart_data] (where Image is a FastMCP Image content block pointing to the generated PNG).
  • If generate_image is False, returns the raw JSON dictionary chart_data directly. Contains keys: thien_ban (demographics, pillars, element, destiny) and dia_ban (12 houses with stars).
  • Returns {"error": "error_message"} if calculations fail.