Content
# Ziwei Dou Shu MCP Server
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://github.com/SylarLong/iztro)
A Ziwei Dou Shu calculation server based on [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), using the powerful [iztro](https://github.com/SylarLong/iztro) library to provide accurate Ziwei Dou Shu charting and fortune analysis.
## ✨ Features
- 🌟 **Complete Ziwei Dou Shu Charting** - Supports calculation from both Gregorian and Lunar birthdays
- 📅 **Precise Time Handling** - Retrieves current system time and detailed information
- 🔮 **Fortune Analysis** - Analysis of major and minor cycles
- 🌐 **Multi-Language Support** - Simplified Chinese, Traditional Chinese, English, Japanese, Korean, Vietnamese
- 🔄 **MCP Protocol Compatible** - Seamless integration with AI assistants that support MCP
- ⚡ **Lightweight and Efficient** - Based on Node.js, with fast response times
- 📊 **Structured Data** - Returns complete JSON format chart data
## 🛠️ Tech Stack
- **Node.js** (≥18.0.0) - Runtime environment
- **iztro** (v2.5.3) - Core Ziwei Dou Shu calculation library
- **MCP Protocol** (2024-11-05) - Model Context Protocol
## 📦 Installation
### Prerequisites
- Node.js 18.0.0 or higher
- npm package manager
### Clone the Repository
```bash
git clone https://github.com/wuunicorn/MCPIztro.git
cd MCPIztro
```
### Install Dependencies
```bash
npm install
```
## ⚙️ Configuration
### 1. Create Configuration File
Modify the paths in `ziwei_mcp_config.json` to your actual project paths:
```json
{
"mcpServers": {
"ziwei": {
"command": "node",
"args": ["/path/to/your/project/ziwei_mcp_server.js"],
"env": {
"NODE_PATH": "/path/to/your/project/node_modules"
}
}
}
}
```
### 2. Configure in MCP Client
Add the configuration file content to your MCP client configuration (e.g., Claude Desktop, Cursor, etc.).
## 🚀 Usage
### Start the Server Directly
```bash
npm start
# or
node ziwei_mcp_server.js
```
### Run Tests
```bash
npm test
# or
node test_ziwei.js
```
## 📖 API Documentation
The server provides the following three main tools:
### 1. get_current_time
Gets detailed information about the current system time.
**Parameters:** None
**Returns:**
```json
{
"success": true,
"data": {
"year": 2024,
"month": 8,
"day": 1,
"hour": 15,
"minute": 30,
"second": 45,
"datetime_str": "2024-08-01 15:30:45",
"weekday": "Thursday",
"weekday_cn": "星期四",
"timestamp": 1722513045
}
}
```
### 2. calculate_ziwei
Calculates the Ziwei Dou Shu chart for a specified birthdate.
**Parameters:**
- `birthday` (required): Birthday, format YYYY-MM-DD
- `hour` (optional): Birth hour (0-23), default 0
- `gender` (optional): Gender ("男"/"女"), default "男"
- `type` (optional): Date type ("solar"/"lunar"), default "solar"
- `isLeapMonth` (optional): Whether it is a leap month, default false
- `language` (optional): Language setting, default "zh-CN"
**Example Request:**
```json
{
"birthday": "1990-08-16",
"hour": 14,
"gender": "女",
"type": "solar",
"language": "zh-CN"
}
```
**Returns:** Complete chart data, including information on the twelve palaces, star distribution, brightness, etc.
### 3. get_horoscope
Gets fortune information for a specified birthdate at a specific time.
**Parameters:**
- `birthday` (required): Birthday, format YYYY-MM-DD
- `hour` (optional): Birth hour (0-23), default 0
- `gender` (optional): Gender ("男"/"女"), default "男"
- `type` (optional): Date type ("solar"/"lunar"), default "solar"
- `isLeapMonth` (optional): Whether it is a leap month, default false
- `targetDate` (optional): Target date, format YYYY-MM-DD, default current date
- `language` (optional): Language setting, default "zh-CN"
**Returns:** Fortune information, including major cycles, minor cycles, age, etc.
## 🌐 Supported Languages
| Language Code | Language Name |
|---------------|---------------|
| zh-CN | Simplified Chinese |
| zh-TW | Traditional Chinese |
| en-US | English |
| ja-JP | Japanese |
| ko-KR | Korean |
| vi-VN | Vietnamese |
## 📝 Usage Examples
### Using in MCP Client
After configuration, you can directly use natural language queries in a client that supports MCP:
```
Please create a Ziwei Dou Shu chart for a female born on August 16, 1990, at 2 PM.
```
```
I want to see what this person's fortune is like in 2024.
```
### Direct API Call
```bash
# Get current time
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {}}}' | node ziwei_mcp_server.js
# Calculate chart
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "calculate_ziwei", "arguments": {"birthday": "1990-08-16", "hour": 14, "gender": "女"}}}' | node ziwei_mcp_server.js
```
## 🏗️ Project Structure
```
MCPIztro/
├── README.md # Project documentation
├── package.json # Project configuration and dependencies
├── package-lock.json # Dependency lock file
├── ziwei_mcp_server.js # MCP server main program
├── ziwei_mcp_config.json # MCP configuration file template
├── test_ziwei.js # Test script
└── node_modules/ # Dependency package directory
```
## 🔧 Development
### Test Server Functionality
```bash
node test_ziwei.js
```
### Check Syntax
```bash
node -c ziwei_mcp_server.js
```
### Verify Dependencies
```bash
node -e "import { astro } from 'iztro'; console.log('Dependencies loaded successfully');"
```
## 🤝 Contributing
Welcome to submit Issues and Pull Requests!
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [iztro](https://github.com/SylarLong/iztro) - Provides powerful Ziwei Dou Shu calculation capabilities
- [Model Context Protocol](https://modelcontextprotocol.io/) - Provides standardized protocol support
## 📞 Contact
If you have any questions or suggestions, please contact us through the following methods:
- Submit an [Issue](https://github.com/wuunicorn/MCPIztro/issues)
- Send an email to: wuunicorn@gmail.com
---
**Note:** Ziwei Dou Shu is for reference and entertainment purposes only. Please treat fortune analysis results rationally.
