MCP Chinese Time

A Model Context Protocol (MCP) server for parsing Chinese fuzzy time expressions to standard datetime formats.

Features

• Relative Time: 昨天, 今天, 明天, 三天前, 两周后
• Time Ranges: 昨天到今天, 上周一到周五
• Time of Day: 上午9点, 下午3点30分, 晚上8点
• Holidays: Both solar (国庆节, 劳动节) and lunar (春节, 中秋节, 端午节)
• Specific Dates: 2024年1月1日, 1月15号
• Weekdays: 周一, 上周三, 下周五
• Chinese Numbers: Supports both Arabic (3) and Chinese (三) numerals

Installation

Using pip

pip install mcp-chinese-time

Using uvx (recommended for MCP)

uvx mcp-chinese-time

Usage

As an MCP Server

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "chinese-time": {
      "command": "uvx",
      "args": ["mcp-chinese-time"]
    }
  }
}

VS Code Configuration

Add to your VS Code settings or .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "chinese-time": {
        "command": "uvx",
        "args": ["mcp-chinese-time"]
      }
    }
  }
}

With pip installation

{
  "mcpServers": {
    "chinese-time": {
      "command": "mcp-chinese-time"
    }
  }
}

As a Python Library

from mcp_chinese_time import FuzzyTimeParser

parser = FuzzyTimeParser(timezone="Asia/Shanghai")

# Parse relative time
result = parser.parse("昨天")
print(result.value)  # "2024-01-14"

# Parse time range
result = parser.parse("上周一到周五")
print(result.value)  # ["2024-01-08", "2024-01-12"]
print(result.is_range)  # True

# Parse holiday
result = parser.parse("国庆节期间")
print(result.value)  # ["2024-10-01", "2024-10-07"]

# Parse time of day
result = parser.parse("下午3点30分")
print(result.value)  # "2024-01-15 15:30:00"
print(result.is_date_only)  # False

# Parse lunar holiday (requires zhdate)
result = parser.parse("中秋节")
print(result.value)  # "2024-09-17"

Running the Server Directly

# Using the installed command
mcp-chinese-time

# Or using Python module
python -m mcp_chinese_time

API Reference

Tool: parse_time

Parse fuzzy Chinese time expressions to standard datetime format.

Parameters:

Returns:

{
  "success": true,
  "parsed": {
    "value": "2024-01-15",
    "is_range": false,
    "is_date_only": true,
    "original_expression": "今天",
    "confidence": 1.0
  },
  "error": null
}

For time ranges:

{
  "success": true,
  "parsed": {
    "value": ["2024-10-01", "2024-10-07"],
    "is_range": true,
    "is_date_only": true,
    "original_expression": "国庆节期间",
    "confidence": 0.95
  },
  "error": null
}

Supported Expressions

Relative Days

Relative Weeks

Relative Months

Weekdays

Time of Day

Solar Holidays

Lunar Holidays

Development

Setup

# Clone the repository
git clone https://github.com/wyl116/mcp-chinese-time.git
cd mcp-chinese-time

# Install development dependencies
pip install -e ".[dev]"

Running Tests

pytest tests/ -v

Code Quality

ruff check src/ tests/
ruff format src/ tests/

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Acknowledgments

• Built with FastMCP
• Lunar calendar conversion powered by zhdate