# 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.

[![npm version](https://badge.fury.io/js/%40vreme%2Ftemporal-mcp.svg)](https://www.npmjs.com/package/@vreme/temporal-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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**