iztro MCP Server

A Model Context Protocol (MCP) server that exposes the iztro library methods for Zi Wei Dou Shu astrology calculations.

About

This MCP server provides a bridge between the powerful iztro astrology library and MCP-compatible clients, enabling seamless integration of Chinese astrology calculations into AI applications and workflows.

Features

This MCP server provides six main tools:

1. get_astrolabe - Generate an astrolabe using solar calendar date
2. get_horoscope_decades - Get all decadal data for whole life
3. get_horoscope_ages - Get all age data for whole life
4. get_horoscope_years - Get all yearly data for whole life
5. get_horoscope_months - Get monthly data for one year
6. get_mutaged_places - Get the 4 palaces affected by the four transformations (禄权科忌) from a specific palace
7. gen_astrolabe - Generate an astrolabe, decades, years, ages, months in separate JSON files in a specific path

Installation

From npm

npm install -g @xzkcz/iztro-mcp-server

From source

git clone https://github.com/xzkcz/iztro-mcp-server.git
cd iztro-mcp-server
npm install
npm run build

Usage

As a Global Package

After installing globally, you can run the server directly:

@xzkcz/iztro-mcp-server

Development

To run the server in development mode:

npm run dev

Production

To build and run the server:

npm run build
npm start

Testing

Run the test suite:

npm run test            # Run tests once
npm run test:watch      # Run tests in watch mode
npm run test:coverage   # Run tests with coverage report
npm run test:ui         # Run tests with UI

MCP Tools

get_astrolabe

Generate an astrolabe using solar calendar date for Zi Wei Dou Shu astrology analysis.

Parameters:

• date (string, required): Birth date in YYYY-M-D format (e.g., "2000-8-16")
• hour (number, required): Birth hour in 24-hour format (0-23)
• gender (enum, required): Gender of the person ("male" or "female")
• fixLeap (boolean, optional): Whether to fix the leap month (default: true)
• locale (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

get_horoscope_decades

Get all decadal data for whole life.

Parameters:

• date (string, required): Birth date in YYYY-M-D format (e.g., "2000-8-16")
• hour (number, required): Birth hour in 24-hour format (0-23)
• gender (enum, required): Gender of the person ("male" or "female")
• fixLeap (boolean, optional): Whether to fix the leap month (default: true)
• locale (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

get_horoscope_ages

Get all age data for whole life.

Parameters:

• date (string, required): Birth date in YYYY-M-D format (e.g., "2000-8-16")
• hour (number, required): Birth hour in 24-hour format (0-23)
• gender (enum, required): Gender of the person ("male" or "female")
• fixLeap (boolean, optional): Whether to fix the leap month (default: true)
• locale (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

get_horoscope_years

Get all yearly data for whole life.

Parameters:

• date (string, required): Birth date in YYYY-M-D format (e.g., "2000-8-16")
• hour (number, required): Birth hour in 24-hour format (0-23)
• gender (enum, required): Gender of the person ("male" or "female")
• fixLeap (boolean, optional): Whether to fix the leap month (default: true)
• locale (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

get_horoscope_months

Get monthly data for one year.

Parameters:

• year (number, required): Year to get monthly data for (e.g., 2024)
• fixLeap (boolean, optional): Whether to fix the leap month (default: true)
• locale (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

get_mutaged_places

Get the 4 palaces that are affected by the four transformations (禄权科忌) from a specific palace.

Parameters:

• date (string, required): Birth date in YYYY-M-D format (e.g., "2000-8-16")
• hour (number, required): Birth hour in 24-hour format (0-23)
• gender (enum, required): Gender of the person ("male" or "female")
• palaceName (number | string, required): Palace to analyze. Can be either:
  • A number (0-11): Palace index (0=命宫, 1=兄弟, 2=夫妻, 3=子女, 4=财帛, 5=疾厄, 6=迁移, 7=奴仆, 8=官禄, 9=田宅, 10=福德, 11=父母)
  • A Chinese string: Palace name (e.g., "命宫", "财帛", "官禄", "夫妻", "子女", "疾厄", "迁移", "奴仆", "田宅", "福德", "父母", "兄弟")
  • An English string: Palace name (e.g., "soul", "wealth", "career", "spouse", "children", "health", "surface", "friends", "property", "spirit", "parents", "siblings")
• fixLeap (boolean, optional): Whether to fix the leap month (default: true)
• locale (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

Returns: A structured response containing:

• sourcePalace: Information about the source palace
• mutagedPlaces: Array of 4 elements corresponding to the four transformations [禄, 权, 科, 忌]
• metadata: Birth information and generation timestamp

gen_astrolabe

Generate an astrolabe, decades, years, ages, months in separate JSON files in a specific path.

Parameters:

• date (string, required): Birth date in YYYY-M-D format (e.g., "2000-8-16")
• hour (number, required): Birth hour in 24-hour format (0-23)
• gender (enum, required): Gender of the person ("male" or "female")
• path (string, required): Absolute path to the directory where the JSON files will be saved
• fixLeap (boolean, optional): Whether to fix the leap month (default: true)
• locale (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

Returns:

• success: Boolean indicating success
• files: Array of strings containing the paths of the generated files (astrolabe.json, decades.json, ages.json, years.json, months.json)

Example Usage

When connected to an MCP client, you can use these tools like:

{
  "tool": "get_astrolabe",
  "parameters": {
    "date": "2000-8-16",
    "hour": 2,
    "gender": "male",
    "fixLeap": true,
    "locale": "zh-CN"
  }
}

{
  "tool": "get_mutaged_places",
  "parameters": {
    "date": "2000-8-16",
    "hour": 2,
    "gender": "female",
    "palaceName": "命宫",
    "fixLeap": true,
    "locale": "zh-CN"
  }
}

{
  "tool": "get_mutaged_places",
  "parameters": {
    "date": "2000-8-16",
    "hour": 2,
    "gender": "male",
    "palaceName": 0,
    "fixLeap": true,
    "locale": "zh-CN"
  }
}

{
  "tool": "get_mutaged_places",
  "parameters": {
    "date": "2000-8-16",
    "hour": 2,
    "gender": "female",
    "palaceName": "soul",
    "fixLeap": true,
    "locale": "en-US"
  }
}

MCP Client Configuration

To use this server with an MCP client, add it to your client configuration:

{
  "mcpServers": {
    "iztro-astrology": {
      "command": "@xzkcz/iztro-mcp-server",
      "args": []
    }
  }
}

Requirements

• Node.js >= 18.0.0
• npm or yarn

Dependencies

• fastmcp: TypeScript framework for building MCP servers
• iztro: Lightweight JavaScript library for Zi Wei Dou Shu astrolabe generation
• zod: Schema validation library

Development

Project Structure

src/
├── index.ts              # Main MCP server implementation
├── getAstroMonth.ts      # Utility for astrology month calculations
├── getAstroYear.ts       # Utility for astrology year calculations
├── hourToTimeIndex.ts    # Utility for time index conversion
└── tests/
    ├── bySolar.test.ts       # Tests for solar calendar functions
    ├── getAstroMonth.test.ts # Tests for astrology month utilities
    ├── getAstroYear.test.ts  # Tests for astrology year utilities
    ├── hourToTimeIndex.test.ts # Tests for time index utilities
    ├── integration.test.ts   # Integration tests
    ├── iztro.test.ts         # Tests for iztro library integration
    └── tools.test.ts         # Tests for MCP tools

Building

npm run build

Testing

npm run test:run          # Run all tests
npm run test:coverage     # Run tests with coverage

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite
6. Submit a pull request

Links

• Repository: https://github.com/xzkcz/iztro-mcp-server
• Issues: https://github.com/xzkcz/iztro-mcp-server/issues
• npm Package: https://www.npmjs.com/package/@xzkcz/iztro-mcp-server
• iztro Library: https://github.com/SylarLong/iztro
• Model Context Protocol: https://modelcontextprotocol.io/

License

This project is licensed under the MIT License - see the LICENSE file for details.