Log inSubmit server
TuViMCP logo

TuViMCP

by nmhaaa3218

Calculates Vietnamese Tử Vi charts, evaluates 51 traditional patterns, checks auspicious dates, and renders chart images.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install TuViMCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "nmhaaa3218-tuvimcp": {
      "command": "uvx",
      "args": [
        "tuvi-mcp-server"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

uvx tuvi-mcp-server

Process exited before answering initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 7d ago.

Overview

nmhaaa3218/TuViMCP MCP server calculates Vietnamese Tử Vi horoscope charts from solar or lunar birth details and returns structured JSON for agent interpretation. It can evaluate 51 traditional formations, calculate transit periods, check auspicious dates and times, convert calendars, and optionally render PNG chart images. Run it locally over stdio for desktop MCP clients or expose it through streamable HTTP for remote deployments. Reach for it when an agent needs Vietnamese horoscope calculations rather than a general-purpose calendar or astrology API.

Use cases

  • Generate Vietnamese Tử Vi birth charts from solar or lunar dates
  • Evaluate traditional Cách Cục formations in an agent workflow
  • Calculate transit periods for a target year, month, and day
  • Check auspicious dates, hours, and travel directions
  • Render calculated charts as PNG images

Key features

  • Solar and lunar birth-date chart generation
  • 51 traditional Cách Cục evaluations
  • Transit star and Vận Hạn calculations
  • Auspicious date and time analysis
  • Structured JSON chart output
  • Optional PNG chart rendering

Tools48

What TuViMCP lets your agent do. Expand a tool for its parameters.

Self-reported~126 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

7/7 checks healthy over the last 45d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 7d ago via OSV.dev · tuvi-mcp-server (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars7Stargazers on the source repository.
Last commit15d agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Tools exposed48Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How TuViMCP works

What nmhaaa3218/TuViMCP MCP server does

The nmhaaa3218/TuViMCP MCP server provides a Python implementation of Vietnamese Tử Vi chart calculation through the Model Context Protocol. It accepts a person’s name, birth date, birth hour, gender, calendar type, and timezone, then produces a structured chart containing Thiên Bàn data, Địa Bàn data, 12 houses, and star placements.

Chart generation can also identify 51 traditional Cách Cục formations. Matching results include explanatory material such as descriptions, Cổ Ca poems, Bình Chú commentary, and stated advantages or disadvantages. This makes the output suitable for an agent that needs to present or explain calculated results, while keeping the underlying response in JSON form.

The server also covers Vận Hạn analysis for a selected year, month, and day. It calculates transit stars and exposes Đại Hạn, Tiểu Hạn, Nguyệt Hạn, and Nhật Hạn periods. Calendar-related functions evaluate Hoàng Đạo and Hắc Đạo, 12 Trực, 28 Tú, Tiết Khí, travel directions, and auspicious hours.

How it works

nmhaaa3218/TuViMCP runs locally and wraps the same typed calculation library used by the project’s Python API. MCP clients can invoke the server through standard input/output or through streamable HTTP. The default HTTP port is 1850, with host and port override options available at startup.

Birth dates may be supplied as solar or lunar dates. Hour input accepts a local clock value such as 14:30, a Vietnamese Earthly Branch name such as Ngọ or Tý, or a numeric branch index. Gender accepts Vietnamese values such as Nam and Nữ, case-insensitively. The server can return a rendered PNG path when image generation is requested.

The calculation engine uses Vietnamese local time, GMT+7, by default. A timezone can be supplied as an integer or an offset string such as 8:30. The timezone affects solar-to-lunar date boundary rounding; the civil hour branch is derived from the supplied local clock time.

Setup and configuration

Install the published package with:

Terminal
pip install tuvi-mcp-server

For a local development checkout, create a Python virtual environment and install the package in editable mode with its test extras. Start the default stdio server with:

bash
.venv/bin/tuvi-mcp

That mode is documented for Claude Desktop and Cursor. To use streamable HTTP, run:

bash
.venv/bin/tuvi-mcp --http

The HTTP listener uses port 1850 by default. --host and --port can change the bind address and port. The MCP tools do not require external authentication or network rate limiting.

Tools and capabilities

The nmhaaa3218/TuViMCP MCP server exposes capabilities for:

  • Generating a complete horoscope from birth details.
  • Returning structured chart_data, including Thiên Bàn and Địa Bàn information.
  • Evaluating the 51 supported traditional formations.
  • Calculating transit stars and the Đại Hạn, Tiểu Hạn, Nguyệt Hạn, and Nhật Hạn periods.
  • Converting between solar and lunar calendar representations.
  • Checking auspicious dates, hours, directions, and related traditional calendar indicators.
  • Rendering a chart as a PNG image when generate_image is enabled.

The bundled Python library also offers typed result objects and optional SQLite helpers for saving, listing, retrieving, and deleting horoscope profiles. That persistence layer belongs to the library; MCP operations themselves are stateless and do not require a database.

Limitations and notes

nmhaaa3218/TuViMCP follows standard consensus calculation rules and does not provide selectable Nam Phái, Bắc Phái, or custom star-distribution configurations. Traditional Tử Vi schools can differ in calculations, rankings, elemental assignments, and interpretation, so its output should be treated as a computational reference rather than a definitive reading.

The timezone must represent the local civil time used for the birth details. Historical or far-future dates involving lunar leap months may vary because mappings follow the stated Vietnamese lunar-calendar methodology. Chart rendering writes a PNG to a temporary local filesystem location and returns its path, so an MCP client must be able to access or transfer that file if the image is to be shown to a user.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about TuViMCP

nmhaaa3218/TuViMCP is an MCP server that connects AI agents to a Vietnamese Tử Vi horoscope calculation engine. Its main tools generate solar or lunar birth charts, evaluate 51 traditional formations, calculate transit periods, check auspicious dates and times, convert calendars, and optionally render chart images as PNG files.

Install it from PyPI with `pip install tuvi-mcp-server`. After installation, start the stdio server with `.venv/bin/tuvi-mcp`, or use the installed command in the Python environment where the package was added.

Yes, Cursor is documented as a client for the server’s stdio mode. Start the server with `.venv/bin/tuvi-mcp` and configure Cursor to launch that command.

Run `.venv/bin/tuvi-mcp --http` to start streamable HTTP mode. It listens on port 1850 by default; use `--host` and `--port` to override the bind address and port.

No, the MCP tools require neither external authentication nor a database. They run locally and are stateless; the separate Python library includes optional SQLite utilities for persisting horoscope profiles.

Related MCP servers

All in Spirituality & Esoterica All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewTuViMCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/nmhaaa3218-tuvimcp?style=directory)](https://allmcps.com/mcp/nmhaaa3218-tuvimcp)
HTML Embed
<a href="https://allmcps.com/mcp/nmhaaa3218-tuvimcp"><img src="https://allmcps.com/api/badge/nmhaaa3218-tuvimcp?style=directory" alt="TuViMCP on AllMCPs" /></a>