home / mcp / temporal cortex mcp server

Temporal Cortex MCP Server

Provides deterministic temporal context, calendar RRULE expansion, and safe multi-calendar booking for AI agents.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "billylui-temporal-cortex-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@temporal-cortex/cortex-mcp"
      ],
      "env": {
        "TIMEZONE": "America/New_York",
        "WEEK_START": "monday",
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

You deploy and run the Temporal Cortex MCP Server to give AI agents reliable, time-aware calendar skills. It provides deterministic temporal reasoning, safe booking with two-phase commit, and unified multi-calendar availability, enabling accurate scheduling and avoidance of double-bookings.

How to use

You run the MCP server locally and connect your calendar-aware AI clients to it. Start by launching the MCP server in stdio mode using the provided command, then configure your MCP clients to reach it. Your AI agents can then ask for the current time, convert time expressions, check availability across calendars, and book slots safely with concurrency control.

How to install

Prerequisites: install Node.js 18 or newer. You also need Google Calendar access and OAuth credentials.

# Install and run the MCP server with NPX (stdio transport)
npx -y @temporal-cortex/cortex-mcp

Configuration and usage notes

Configure your MCP client to launch the server with the appropriate environment variables. The following configuration example shows how to start the MCP server in stdio mode and provide Google OAuth credentials and a preferred timezone.

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}

First-time setup and auth flow

On first run, you need Google Calendar access. You can authenticate before connecting or let the server prompt when a client connects. The authentication stores credentials locally for reuse.

npx @temporal-cortex/cortex-mcp auth

Security and transport options

The MCP server supports stdio transport for local clients and HTTP transport if you enable HTTP_PORT. In HTTP mode, the server exposes a web endpoint and uses session management and origin checks.

# Example HTTP mode (port specified)
HTTP_PORT=8009 npx @temporal-cortex/cortex-mcp

Available tools

get_temporal_context

Returns current time, timezone, UTC offset, DST status, and day of the week. Used to establish the temporal context for all subsequent operations.

resolve_datetime

Converts human expressions like 'next Tuesday at 2pm' into an RFC 3339 timestamp.

convert_timezone

Converts a given RFC 3339 timestamp between IANA timezones.

compute_duration

Calculates the duration between two timestamps in days, hours, and minutes in a human-readable form.

adjust_timestamp

DST-aware adjustment of timestamps, ensuring wall-clock consistency across DST transitions.

list_events

Lists calendar events in a time range. Outputs in TOON or JSON for consumption by AI agents.

find_free_slots

Finds available time slots by computing actual gaps between events across calendars.

expand_rrule

Expands RRULEs into concrete instances, handling DST, BYSETPOS, leap years, and complex intervals.

check_availability

Checks whether a specific time slot is free against events and active locks.

get_availability

Provides a merged free/busy view across multiple calendars with privacy controls.

book_slot

Safely books a calendar slot using a Two-Phase Commit mechanism to prevent conflicts.