Time Service
A Model Context Protocol (MCP) server that provides time-related tools for Claude
Ask AI about Time Service
Powered by Claude Β· Grounded in docs
I know everything about Time Service. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Time Service
π The most comprehensive time handling MCP server - Beyond simple timezone conversion
Time Service is a powerful Model Context Protocol (MCP) server that brings enterprise-grade time manipulation capabilities to your AI assistant. With 8 specialized tools, it goes far beyond basic timezone queries to solve real-world scheduling, calculation, and business time challenges.
Quick Links: π¦ npm Package β’ π GitHub β’ π Changelog β’ π MCP Docs
β¨ Why Time Service?
π― Complete Solution
Time Service provides 8 comprehensive tools covering every time-handling scenario:
- β Time queries - Current time, timestamps, multiple timezones
- β Time calculations - Add/subtract time, calculate differences
- β Timezone operations - Convert between any timezones
- β Business scenarios - Calculate business days, find next occurrences
π Killer Features
π Batch Operations Query multiple timezones in one call - reduce API requests and get instant global time overview:
One call β All timezones with UTC offsets
π Business Day Intelligence Automatically skip weekends when calculating deadlines - perfect for project management:
"Add 5 business days to today" β Automatically excludes weekends
β° Smart Scheduling Find next occurrence with flexible conditions:
"Next Monday at 2pm" β
"Next 15th of the month" β
"Next Friday at 14:00" β
π¨ Flexible Formatting 4 built-in formats plus custom configurations:
- ISO 8601:
2024-01-15T10:30:00Z - Unix timestamp:
1705315800 - Human-readable:
Monday, January 15, 2024 at 10:30:00 AM - Custom: Any format you need
πͺ Production Ready
- β 100% Test Coverage - 115 comprehensive test cases
- β Fully Typed - Complete TypeScript type system
- β Well Documented - Clear examples and guides
- β Zero Installation - Use directly with npx/bunx
π οΈ Available Tools
| Tool | What It Does | Use Case |
|---|---|---|
| get_current_time | Get current time in any format/timezone | Check time across timezones |
| get_timestamp | Get Unix timestamp (seconds/milliseconds) | Generate timestamps for APIs |
| add_time | Add/subtract time periods | "What's the time 3 days from now?" |
| time_diff | Calculate time difference | "How many hours until deadline?" |
| convert_timezone | Convert time between timezones | "NYC 9am is what time in Tokyo?" |
| get_multiple_timezones | Get time in multiple zones at once | Display world clock |
| get_business_days | Calculate business days (skip weekends) | Project deadline calculations |
| next_occurrence | Find next specific day/date/time | "When's next Monday?", "Next 15th?" |
π¦ Installation
Add to your MCP client configuration:
{
"mcpServers": {
"time-service": {
"command": "npx",
"args": ["-y", "@qiyuey/time-service"]
}
}
}
Supported runtimes: npm (Node.js), bun
π― Usage Examples
Real-World Scenarios
Scenario 1: Global Team Coordination
User: "What time is it in our offices in New York, London, and Tokyo?"
Time Service: Uses get_multiple_timezones
β Returns all three times with UTC offsets in one response
Scenario 2: Project Deadline Calculation
User: "If we start today, what's the date 10 business days from now?"
Time Service: Uses get_business_days
β Automatically skips weekends, returns exact date
Scenario 3: Meeting Scheduling
User: "Convert 2pm EST to Tokyo time"
Time Service: Uses convert_timezone
β Handles daylight saving automatically
Scenario 4: Recurring Event Planning
User: "When's the next Monday at 9am?"
Time Service: Uses next_occurrence
β Finds exact date and time
API Examples
Get time in multiple timezones:
{
"name": "get_multiple_timezones",
"arguments": {
"timezones": ["America/New_York", "Europe/London", "Asia/Tokyo"],
"format": "readable"
}
}
Calculate business days:
{
"name": "get_business_days",
"arguments": {
"startDate": "2024-01-15T00:00:00Z",
"days": 5,
"excludeWeekends": true
}
}
Find next occurrence:
{
"name": "next_occurrence",
"arguments": {
"dayOfWeek": 1,
"time": "14:00"
}
}
πΊοΈ Roadmap
P0 - Core Improvements β
- β Code Optimization (v0.3.1) - Extracted shared utilities, achieved 100% function coverage
- β Comprehensive Testing - 115 test cases covering all scenarios
P1 - High Priority (Coming Soon)
- π Enhanced Documentation - Detailed guides and tutorials
- π³ Docker Support - Container deployment ready
- π Platform Integration Guides - Claude Desktop, Zed, VS Code
- β‘ Performance Boost - Caching and optimization
P2 - Medium Priority (Future)
- π Internationalization - Multi-language support
- π Advanced Calculations - Holiday support, working hours
- π Analytics - Usage statistics and monitoring
- π Python Version - Expand to Python ecosystem
P3 - Long-term Vision
- π Auto-updating Timezone Database - Always current
- π Web API Service - HTTP API version
- π¨ Custom Holiday Calendars - Region-specific holidays
- π Third-party Integrations - Calendar systems, project management tools
π€ Contributing
We welcome contributions! Here's how you can help:
Priority Areas:
- π³ Docker deployment configurations
- π Documentation and integration guides
- β¨ New time calculation features
- π Performance optimizations
How to Contribute:
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
π Resources
- π¦ npm Package
- π GitHub Repository
- π Release Notes
- π Issue Tracker
- π MCP Protocol
- π€ Claude AI
π FAQ
Q: What makes Time Service special?
A: We provide 8 comprehensive tools including business day calculations, batch timezone queries, smart occurrence finding, and flexible formatting options - a complete solution for all your time-handling needs.
Q: Do I need to install anything?
A: No! Use npx -y @qiyuey/time-service directly in your MCP configuration.
Q: What timezones are supported?
A: All IANA timezone names (e.g., America/New_York, Asia/Tokyo, Europe/London).
Q: Can I use custom date formats?
A: Yes! Supports ISO, Unix, human-readable, and custom Intl.DateTimeFormat configurations.
Q: Is it production-ready?
A: Absolutely! 100% function coverage, 115 test cases, fully typed, and actively maintained.
π License
This project is licensed under the MIT License - see the LICENSE file for details.
This project also supports the Anti-996 License. By using this software, you agree to comply with labor laws and regulations, and not to force employees to work overtime without reasonable compensation.
Additional Terms:
- This software is for learning, research, and legitimate business use only
- Users must comply with local labor laws and regulations
- Prohibited from using this software to exploit workers or violate labor rights
MIT Β© qiyuey
