Vreme Documentation
Natural language time intelligence for AI assistants.
Quick Start
Get Vreme running in 2 minutes.
1. Install
The MCP server is published on npm and as a Docker image on Docker Hub.
2. Configure Your AI Client
Add to your MCP client configuration file:
Claude Desktop:
Configuration file location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Add this configuration:
{
"mcpServers": {
"vreme": {
"command": "vreme-temporal-mcp"
}
}
}3. Restart & Test
Restart your AI client completely (quit and reopen).
Then ask: "What time is it in Tokyo?"
You should see a rich response with timezone info, astronomical data, and cultural context.
Troubleshooting
MCP Server Not Appearing in Claude
- Verify the package is installed:
which vreme-temporal-mcp - Check your config file syntax (must be valid JSON)
- Make sure you completely quit and restarted your AI client (not just closed the window)
- Check your client's logs for MCP errors (varies by client/OS)
Installation Fails
- Make sure you have Node.js 18+ installed:
node --version - Try with sudo (macOS/Linux):
sudo npm install -g @vreme/temporal-mcp - On Windows, run terminal as Administrator
Queries Return Errors
- Try simpler queries first: "What time is it in London?"
- Some location names may not be recognized - try major cities
- Check the API status page (if you're getting 500 errors)
What is Temporal Intelligence?
Temporal Intelligence is the ability of an AI system to understand time beyond simple timestamps. It involves three dimensions:
- Chronological Awareness: Timezones, offsets, DST rules.
- Cultural Context: Calendars (Hebrew, Islamic, etc.), holidays, religious observances.
- Contextual Appropriateness: Understanding if a time is "good" for an action (calls, meetings, work).
Standard LLMs are "temporally blind" - they don't know what time it is now, and struggle with relative time calculations. Vreme bridges this gap.
Vreme vs Standard APIs
| Feature | Vreme | WorldTimeAPI | Standard LLM |
|---|---|---|---|
| Natural Language Input | Yes | No | Yes (Hallucinates) |
| Cultural Calendars | 5+ Systems | No | Partial |
| Astronomical Data | Yes (Precise) | No | No |
| Activity Appropriateness | Yes | No | Inconsistent |
Available Tools
Vreme provides 69 specialized temporal intelligence tools organized into 16 categories:
- Core Temporal Tools (7) - Time queries, prayer times, activity appropriateness
- Holiday & Business Time (10) - 247+ countries, business day calculations
- Advanced Temporal Processing (18) - Time arithmetic, phrase resolution, conflict checking, duration calculations
- Calendar & Recurrence (4) - Multi-calendar alignment, RRULE expansion
- Fuzzy Time (3) - Uncertain time representations
- Astronomical (7) - Sunrise/sunset, zodiac, moon phases
- Duration & Period (5) - Duration calculations, period analysis, age calculations
- Timezone Offset (3) - Timezone offset calculations, DST transitions, timezone metadata
- Date Range Operations (3) - Date range overlap detection, containment checks, set operations
- Historical & Projection (2) - Historical day of week facts, date projections
- Temporal Pattern Detection (2) - Pattern detection, frequency analysis
- Weekday Finder (1) - Find next/previous/closest weekday
- Business Days Calculator (1) - Calculate business days between dates
- Nth Occurrence Finder (1) - Find nth occurrence of weekday
- Time in Timezone Calculator (1) - Convert datetime to specific timezone
- Observances & Cultural (3) - Awareness days, tech holidays, commemorations
Example Queries
Get more examples on the Examples page.