# Vreme Temporal MCP
**Temporal intelligence for AI assistants**
Give your AI assistant rich temporal awareness — timezone intelligence, cultural calendars, astronomical events, and time-sensitive context.
Works with **Cursor**, **VS Code**, **Claude Desktop**, **Continue**, **Cline**, and any **MCP-compatible** client.
[](https://www.npmjs.com/package/@vreme/temporal-mcp)
[](https://opensource.org/licenses/MIT)
## What This Does
Instead of just knowing what time it is, your AI gets **rich temporal context**:
```
You: "What time is it in Tokyo?"
Claude: "Sunday, November 30, 2025 at 1:36 PM JST. Sunset in 2 hours 51 minutes.
🌅 Sunrise: 6:31 AM
🌇 Sunset: 4:28 PM
🌙 Moon: Full Moon (70% illuminated)
📅 Hebrew: 10 Kislev 5786
📅 Islamic: 9 Jumada al-Thani 1447 AH
📅 Chinese: Year 2025, Month 10, Day 11 (Metal Snake)
⏰ Weekend - Not appropriate for work calls"
```
## Features
- **🌍 200+ Timezones** - All pytz timezones with DST handling
- **📅 9 Cultural Calendars** - Hebrew, Islamic, Chinese, Hindu, Persian, Buddhist, Bahá'í, Ethiopian, Mayan
- **🕌 Islamic Prayer Times** - All 5 daily prayers with qibla direction
- **🌅 Astronomical Events** - Sunrise, sunset, moon phases, twilight times
- **✅ Activity Appropriateness** - Smart recommendations for calls, meetings, work
- **🍽️ Religious Observances** - Fasting detection, work restrictions, holiday awareness
- **💬 Natural Language** - No rigid schemas, just ask naturally
## Installation
```bash
npm install -g @vreme/temporal-mcp
```
## Configuration
Add to your MCP client configuration:
**Claude Desktop:**
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"vreme": {
"command": "vreme-temporal-mcp"
}
}
}
```
**Continue / Cline:**
Add to your MCP configuration following their respective setup guides.
Restart your AI client and you're ready!
## Example Queries
### Time & Timezones
- "What time is it in Tokyo?"
- "Current time in New York"
- "What timezone is Paris in?"
### Cultural Intelligence
- "Is it Shabbat in Jerusalem?"
- "Is it Ramadan?"
- "When is Chinese New Year?"
- "What's the Hebrew date today?"
- "When is Diwali 2025?"
### Activity Appropriateness
- "Is it a good time to call someone in Tokyo?"
- "Can I email someone in Jerusalem right now?"
- "Should I call Berlin now?"
### Astronomical Data
- "What time is sunrise in Tokyo?"
- "When does the sun set in Paris?"
- "What's the moon phase?"
### Prayer Times
- "What are prayer times in Dubai?"
- "When is Fajr in Istanbul?"
- "Prayer times in New York"
### Time Until
- "How long until sunset?"
- "Time until sunrise in Berlin"
## How It Works
The MCP server connects your AI client to the [Vreme Time API](https://api.vreme.ai), which provides:
1. **Natural language parsing** - Understands your questions
2. **Timezone calculations** - Accurate time conversions
3. **Cultural calendar conversions** - 9 calendar systems
4. **Astronomical computations** - Sunrise, sunset, moon data
5. **Activity analysis** - Cultural and temporal appropriateness
All responses include full temporal context, not just clock time.
## Architecture
```
AI Client (Claude Desktop / Continue / Cline)
↓ (MCP Protocol)
@vreme/temporal-mcp
↓ (HTTPS)
api.vreme.ai
↓
Temporal Intelligence Engine
```
- **Stateless** - No data stored, pure computation
- **Fast** - <500ms response time (95th percentile)
- **Reliable** - Built on battle-tested libraries (pytz, astral, hijri-converter)
## Supported Features
### Cultural Calendars (9)
- Hebrew (with holiday detection)
- Islamic (with Ramadan, prayer times)
- Chinese (lunisolar, zodiac animals)
- Hindu (festival dates)
- Persian (Nowruz, etc.)
- Buddhist (Vesak, observances)
- Bahá'í (calendar system)
- Ethiopian (unique calendar)
- Mayan (long count)
### Prayer Times
- All 5 daily prayers (Fajr, Dhuhr, Asr, Maghrib, Isha)
- Multiple calculation methods (MWL, ISNA, Egypt, Makkah, Karachi, Tehran, Jafari)
- Qibla direction to Mecca
- Next prayer countdown
### Religious Observances
- Shabbat detection and times
- Ramadan fasting hours
- Jewish holidays and restrictions
- Work permission status
- Fasting day detection
## Troubleshooting
### MCP Server Not Appearing
- Verify installation: `which vreme-temporal-mcp`
- Check your client's config file syntax (valid JSON)
- Completely restart your AI client (quit and reopen)
### Connection Issues
- Requires internet access (queries api.vreme.ai)
- Check API status: `curl https://api.vreme.ai/health`
- Firewall/VPN may be blocking
### Query Errors
- Try major city names first
- Use simple queries: "What time is it in London?"
- Some obscure locations may not be recognized
## API
This MCP server is powered by the public [Vreme Time API](https://api.vreme.ai).
**Endpoint:** `https://api.vreme.ai/query`
You can also use the API directly:
```bash
curl -X POST https://api.vreme.ai/query \
-H "Content-Type: application/json" \
-d '{"query": "What time is it in Tokyo?"}'
```
## Links
- **Website:** [www.vreme.ai](https://www.vreme.ai)
- **Documentation:** [www.vreme.ai/docs](https://www.vreme.ai/docs)
- **Examples:** [www.vreme.ai/docs/examples](https://www.vreme.ai/docs/examples)
- **GitHub:** [github.com/vreme-ai/temporal-mcp](https://github.com/vreme-ai/temporal-mcp)
- **API:** [api.vreme.ai](https://api.vreme.ai)
## License
MIT License - Free and open source forever.
## About Vreme
Vreme (Bulgarian: "time") is building temporal intelligence for AI. This time service is the first product — validating the architecture for our upcoming temporal memory service.
**Time, understood.** Your AI knows what time it is anywhere, respects cultural calendars, and understands contextual appropriateness.
**Memory, preserved.** Coming Q2 2026: Your AI remembers every conversation, every insight, every step of your learning journey.
---
**Questions?** hello@vreme.ai
**Built with ❤️ for temporal awareness**
