Chinese Time

PyPI version Python 3.10+ License: MIT

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:

Parameter	Type	Required	Default	Description
expression	string	Yes	-	Fuzzy time expression in Chinese
timezone	string	No	"Asia/Shanghai"	Timezone for parsing

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

Expression	Description
今天, 今日	Today
昨天, 昨日	Yesterday
前天, 前日	Day before yesterday
大前天	3 days ago
明天, 明日	Tomorrow
后天, 后日	Day after tomorrow
大后天	3 days from now
N天前	N days ago
N天后	N days from now

Relative Weeks

Expression	Description
本周, 这周	This week
上周, 上一周	Last week
上上周	2 weeks ago
下周, 下一周	Next week
下下周	2 weeks from now
N周前	N weeks ago
N周后	N weeks from now

Relative Months

Expression	Description
本月, 这个月	This month
上个月, 上月	Last month
下个月, 下月	Next month
N个月前	N months ago
N个月后	N months from now

Weekdays

Expression	Description
周一 ~ 周日	Weekday (this week)
星期一 ~ 星期日	Weekday (this week)
上周X	Last week's weekday
下周X	Next week's weekday

Time of Day

Expression	Description
上午X点	X AM
下午X点	X PM
晚上X点	X PM (evening)
X点Y分	X:Y

Solar Holidays

Expression	Date
元旦	Jan 1
情人节	Feb 14
劳动节, 五一	May 1-5
儿童节	Jun 1
国庆, 国庆节	Oct 1-7
圣诞, 圣诞节	Dec 25
清明, 清明节	Apr 4-5

Lunar Holidays

Expression	Lunar Date
春节, 过年	1st month, 1st day
除夕, 年三十	12th month, 30th day
元宵, 元宵节	1st month, 15th day
端午, 端午节	5th month, 5th day
七夕, 七夕节	7th month, 7th day
中秋, 中秋节	8th month, 15th day
重阳, 重阳节	9th month, 9th day

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