TuViMCP

TuViMCP is a Python-based Model Context Protocol (MCP) server specifically designed for calculating and managing Vietnamese Tử Vi (Zi Wei Dou Shu) charts. Its design goal is to output clean, structured JSON data, enabling LLM agents to easily read, interpret, and explain it to users.

Purpose

This tool is aimed at developers and agent applications that need to programmatically generate and analyze Vietnamese Tử Vi charts. It can be used both as an MCP server for invocation by LLM clients and as a Python library directly integrated into scripts, notebooks, or web backends.

Main Capabilities

• Chart Generation: Convert solar or lunar birth dates and times into a complete Tử Vi chart, including the Heavenly Plate (Thiên Bàn) and Earthly Plate (Địa Bàn), with a total of 12 palaces and more than 100 stars.
• 51 Pattern Evaluation Engine: Automatically identify all 51 traditional patterns (the Zhongzhou sect's 51 patterns) when generating a chart, returning the matched patterns along with their descriptions, ancient songs (Cổ Ca), commentaries (Bình Chú), and strengths/weaknesses (Ưu/Khuyết điểm).
• High-Quality Image Rendering: Generate beautiful, printable chart images, color text according to the Five Elements (Wood green, Fire red, Earth yellow, Metal gray, Water blue), provide custom badge frames for Tuần and Triệt, and use geometric connecting lines to highlight the relationship between the Life Palace and the Body Palace.
• Fortune Period Analysis (Vận Hạn): Calculate flowing stars (Lưu tinh), and map the active major period (Đại Hạn), minor period (Tiểu Hạn), monthly period (Nguyệt Hạn), and daily period (Nhật Hạn) for any target year, month, or day.
• Auspicious Day and Hour Lookup: Evaluate the yellow/black path (Hoàng Đạo/Hắc Đạo), the 12 Jian Chu (12 Trực), the 28 Mansions (28 Tú), solar terms (Tiết Khí), travel directions, and auspicious hours for any calendar date.
• Local Persistence (Python Library): Built-in SQLite database utilities (tuvi_mcp.database) for Python library users to save, retrieve, list, and delete chart records. The MCP tool itself is stateless and does not require a database.
• Flexible Hour Mapping: Automatically map calendar times (such as "14:30") or string names (such as "Ngọ", "Tý") to the correct earthly branch hour index.
• Local inline (standalone) : Internally contains the core ansaotuvi calculation logic, with custom Tuần/Triệt dual-palace corrections.

How to Use

Can be installed from PyPI via tuvi-mcp-server. Development and contribution setup: create a virtual environment (python3 -m venv .venv), install the package in editable mode (.venv/bin/pip install --upgrade pip and .venv/bin/pip install -e ".[test]"), run tests (.venv/bin/pytest). The server can be run over HTTP (default port 1850), and the host and port can also be overridden.

Tool API Reference

All tools run locally in the MCP environment, with no external authentication or network rate limits.

generate_horoscope: Generates a complete Zi Wei horoscope based on raw birth information, with optional high-quality horoscope image rendering. Parameters include name (name, default "Khách"), day (birth day 1-31), month (birth month 1-12), year (birth year), hour_val (birth hour, such as "14:30", "Ngọ", "Tý", or Earthly Branch index 1-12), gender_val (gender "Nam" or "Nữ", case-insensitive), is_solar (True for solar calendar, False for lunar calendar, default True), current_year (optional, the year for viewing transit stars/periods, default current year), generate_image (optional, whether to generate and return a high-quality horoscope image, default True), timezone (optional, the civil timezone UTC offset of the birthplace, accepts integers such as 7, -5, or h:30 strings such as "7:30", "-5:30", default 7, i.e. Vietnam ICT). If generate_image is True, returns a list containing [Image, chart_data]; if False, directly returns the raw JSON dictionary chart_data, containing the keys thien_ban (demographics, Four Pillars, Five Elements, destiny) and dia_ban (12 palaces and stars). On calculation failure, returns {"error": "error_message"}.

get_van_han: Calculates the annual transit stars and active palaces for the target period (major limit, minor limit, monthly limit, daily limit). Note: current_year, current_month, and (if provided) current_day represent the lunar year, month, and day. To view a solar calendar period (such as October 2026), you must first use convert_calendar to convert. Parameters include birth parameters (name, day, month, year, hour_val, gender_val, is_solar), current_year (target lunar year, default current year), current_month (target lunar month 1-12, default 1), current_day (optional, target lunar day 1-30, enables daily limit), timezone (optional, same as generate_horoscope). Returns a dictionary containing person_details (Heavenly Stems and Earthly Branches), target_period (parsed age and target), transit_stars, dai_han, tieu_han, nguyet_han, and (if current_day is provided) nhat_han. On invalid input, returns {"error": "error_message"}.

convert_calendar: Converts dates between the solar calendar (Dương lịch) and the lunar calendar (Âm lịch). Parameters include day, month, year, from_solar (True for solar to lunar, default; False for lunar to solar), lunar_leap (used only when from_solar is False, True if the input lunar month is a leap month), timezone (timezone offset, accepts integer hours such as 7, -5, 9 or h:30 strings such as "7:30", "-5:30", "9:30", default 7). If from_solar is True, returns a dictionary containing lunar_day, lunar_month, lunar_year, lunar_leap, and a formatted string date; if False, returns a dictionary containing solar_day, solar_month, solar_year, and a formatted string date. On date parameter validation failure, returns {"error": "error_message"}.

check_auspicious_date: Evaluates the auspicious day, auspicious hours, 12 Jianchu, 28 Mansions, solar terms, and travel directions for a given date. Parameters include day (optional, defaults to today), month (optional, defaults to the current month), year (optional, defaults to the current year), is_solar (optional, True for the solar calendar, which is the default; False for the lunar calendar), timezone (optional, same as generate_horoscope). Returns a dictionary containing duong_lich, am_lich, can_chi_ngay, ngay_hoang_dao, truc_ngay, nhi_thap_bat_tu, huong_xuat_hanh, gio_hoang_dao, tiet_khi_hien_tai, tiet_khi_tiep_theo.

Python Library API

In addition to the MCP server, tuvi-mcp-server also provides a typed, easy-to-use Python API that can be used directly in scripts, notebooks, or web backends. The MCP tools wrap the same library, so whether you call Horoscope.from_birth(...).chart() or call the generate_horoscope tool from an MCP client, the behavior is exactly the same.

Use Cases

• Provide LLM agents with Vietnamese Zi Wei Dou Shu chart calculation and interpretation capabilities.
• For developers building astrology-related applications, websites, or chatbots.
• Scenarios that require batch generation, analysis, or management of horoscope archives.
• Query auspicious days and hours to arrange activities such as weddings, business openings, groundbreaking, and travel.

Limitations

• Time zone: Calculations use the Vietnam local time zone (GMT+7) by default. Other birthplaces require explicitly passing the time zone (timezone accepts an integer such as 8 or an h:30 string such as "8:30"); when omitted, it defaults to 7. The astronomical engine only uses the provided time zone for boundary rounding of solar↔lunar dates; the civil hour (chi giờ) is always derived from the local clock time provided by the user.
• Calendar boundaries: Core calculations are stable for modern birth years, but traditional leap months (tháng nhuận) follow the standard Vietnamese lunar calendar mapping (Hoang Nam Dia method), which may differ in historical or far-future years.
• Schools (Phái): Star distribution follows standard commonconsensus calculations. Custom star weights/distributions (such as Southern school, Northern school, or custom configurations) are not supported.
• Accuracy, methodology, and traditional disclaimer: Vietnamese Zi Wei Dou Shu is a very rich astrological methodology, with multiple traditional schools (such as the Southern school and the Northern school). Calculation parameters, star grades, Five Elements determinations, and interpretations may vary depending on the specific lineage or school. The output of this tool is generated strictly according to standard consensus calculation logic and should be regarded as a calculation reference, not an authoritative astrological interpretation.