timecalc

timecalc gives AI agents and humans a small, reliable calculator for date, time-zone, and duration arithmetic. It runs as both a Model Context Protocol (MCP) server and a command-line tool, with both interfaces backed by the same Temporal evaluator.

Why an MCP date calculator?

Date math is deceptively difficult. Month lengths vary, leap years matter, daylight-saving transitions make “one day” different from “24 hours,” and an answer involving “today” is meaningless without a clock and time zone. Language models should not have to approximate those rules or generate ad hoc date code.

The timecalc MCP server lets an agent translate a user's request into one constrained expression and delegate the calculation to Bun's implementation of JavaScript Temporal. The result is typed and machine-readable. Expressions are inspectable, and calculations can be replayed with the same explicit context. The evaluator never uses JavaScript eval and does not parse natural-language dates itself.

At a glance:

• One MCP tool: evaluate_date_expression
• Four Temporal types: PlainDate, Instant, ZonedDateTime, and Duration
• Explicit semantics: calendar dates, absolute instants, zoned times, and durations remain distinct
• Current-time support: deterministic context injection or an opt-in host clock and time zone
• Same behavior everywhere: MCP and CLI share the parser, evaluator, errors, and serialization
• Portable releases: standalone executables do not require Bun at runtime

Guide to this README

• Start with Quick start to run the CLI or configure an MCP client.
• Read Evaluation context and now before handling “now,” “today,” or local-time questions.
• Use the Language overview and Operator reference when writing expressions.
• See the CLI and MCP server sections for complete interface details.
• Building an agent that queries time-series data? See Using timecalc with TimescaleDB.
• Contributors can jump to Architecture and Development.

Quick start

There are three ways to install timecalc. All of them deliver the same standalone executable; none require Bun.

| Method | Best for | Requires | |---|---|---| | Release binary | Fastest startup; any MCP client or shell use | curl and tar (or unzip) | | npm / npx | MCP clients whose config expects an npx command | Node.js 20+ and npm | | Claude Code plugin | Claude Code; installs the MCP server and the Agent Skill together | Claude Code, Node.js 20+ and npm |

Install a release binary (recommended)

On Linux, macOS, or Windows with a POSIX shell such as Git Bash, install the latest release with:

curl -fsSL https://raw.githubusercontent.com/timescale/timecalc-mcp/main/install.sh | sh

The installer detects the operating system and architecture, downloads the matching asset from the latest GitHub release, verifies it against the release's SHA256SUMS, and installs timecalc into $HOME/.local/bin or $HOME/bin. On macOS it also applies a local ad-hoc signature with Bun's recommended JIT entitlements and removes the download quarantine attribute after checksum verification. It never requires Bun. Override the destination or install a specific release when needed:

curl -fsSL https://raw.githubusercontent.com/timescale/timecalc-mcp/main/install.sh \
  | TIMECALC_INSTALL_DIR="$HOME/.local/bin" TIMECALC_VERSION=v0.4.0 sh

Ensure the selected installation directory is on PATH. To inspect the installer before running it, download install.sh and execute it locally with sh install.sh.

For manual installation, download the archive for your platform:

| Platform | Release asset | |---|---| | Linux AMD64 | timecalc-v<version>-linux-amd64.tar.gz | | Linux ARM64 | timecalc-v<version>-linux-arm64.tar.gz | | macOS AMD64 (Intel) | timecalc-v<version>-darwin-amd64.tar.gz | | macOS ARM64 (Apple Silicon) | timecalc-v<version>-darwin-arm64.tar.gz | | Windows AMD64 | timecalc-v<version>-windows-amd64.zip | | Windows ARM64 | timecalc-v<version>-windows-arm64.zip |

Each archive contains timecalc (or timecalc.exe), LICENSE, and NOTICE. The executable includes Bun and all runtime dependencies, so Bun does not need to be installed.

Download SHA256SUMS from the same release and verify the archive before extracting it. For example, on Linux:

ARCHIVE=timecalc-vX.Y.Z-linux-amd64.tar.gz  # replace X.Y.Z
grep -F "$ARCHIVE" SHA256SUMS | sha256sum -c -

On Linux or macOS, extract the archive and install the executable:

VERSION=X.Y.Z                 # replace with the release version
TARGET=linux-amd64            # or linux-arm64 / darwin-amd64 / darwin-arm64
ARCHIVE="timecalc-v${VERSION}-${TARGET}.tar.gz"

mkdir -p "$HOME/.local/bin"
tar -xzf "$ARCHIVE"
install -m 0755 timecalc "$HOME/.local/bin/timecalc"
"$HOME/.local/bin/timecalc" --version

Add $HOME/.local/bin to PATH if it is not already present. Release macOS binaries are ad-hoc signed with Bun's recommended JIT entitlements but are not Developer ID signed or notarized. A manually downloaded binary may therefore require explicit Gatekeeper approval; the verified installer handles the local ad-hoc signing and quarantine removal automatically.

On Windows, verify the archive against SHA256SUMS, extract the .zip, and move timecalc.exe to a directory on PATH. Then confirm the executable from PowerShell:

.\timecalc.exe --version

To develop timecalc or run it from source, see Development.

Install with npm

The executables are also published to npm as @tigerdata/timecalc. That package is a small Node.js launcher; the executable itself comes from a platform-specific package (@tigerdata/timecalc-linux-amd64, @tigerdata/timecalc-darwin-arm64, and so on) selected through optionalDependencies, so npm downloads only the one that matches the machine.

Run without installing:

npx -y @tigerdata/timecalc '(add 2025-01-31 P1M)'

Or install globally:

npm install -g @tigerdata/timecalc
timecalc --version

Each executable embeds the Bun runtime and is 60-90 MB on disk (roughly 25-40 MB compressed), so the first npx run downloads more than a typical npm package. Later runs start from the npm cache. The release binary route above avoids the Node.js launcher and starts slightly faster; prefer it when the MCP client can run an arbitrary command.

Install the Claude Code plugin

For Claude Code, a plugin installs the MCP server and the Agent Skill in one step:

/plugin marketplace add timescale/timecalc-mcp
/plugin install timecalc@timecalc

The plugin starts the server with npx -y @tigerdata/timecalc mcp --system-context, so Node.js and npm must be on PATH. If you already added a timecalc MCP server to Claude Code by hand, remove it first to avoid registering the tool twice. The plugin source lives in plugins/timecalc/.

As an MCP server

For an interactive agent, system-context mode is usually the most useful configuration because many agent harnesses do not expose their current clock or local time zone:

{
  "mcpServers": {
    "timecalc": {
      "command": "timecalc",
      "args": ["mcp", "--system-context"]
    }
  }
}

This still permits a caller to override the clock and zone for reproducible calculations. Use args: ["mcp"] instead when all context must be supplied explicitly. If the client should fetch timecalc itself, use "command": "npx" with "args": ["-y", "@tigerdata/timecalc", "mcp", "--system-context"]. See MCP client configuration for source-checkout configuration.

Typical agent requests include:

• “What date is 30 days from today?”
• “How many calendar months are between these dates?”
• “Convert this timestamp to America/New_York.”
• “Will adding one day across this DST boundary preserve the local hour?”

A current-local-date calculation is explicit in the DSL:

(to-date (with-time-zone (now) (default-time-zone)))

As a CLI

# Deterministic date arithmetic; no clock or zone is needed
timecalc '(add 2025-01-31 P1M)'

# Use the host clock and time zone
timecalc --system-context \
  '(to-date (with-time-zone (now) (default-time-zone)))'

Evaluation context and now

now is represented as a Temporal.Instant: one absolute point on the timeline. A time zone is a separate context value because the same instant can correspond to different local dates around the world.

There are two context modes:

• Deterministic mode is the default. The evaluator does not read the host clock or time zone. Expressions that do not depend on current context work without any extra input. (now) and (default-time-zone) return MISSING_CONTEXT unless their values are supplied explicitly.
• System-context mode is opt-in. --system-context fills missing values from Temporal.Now.instant() and Temporal.Now.timeZoneId(). Explicit now and time-zone inputs always take precedence. The system zone belongs to the process running timecalc; it may be UTC or otherwise differ from the end user's zone, especially in a container or on a remote host.

For a user-specific local-time question, pass that user's IANA zone explicitly instead of assuming the system zone.

The context is resolved once at the start of each evaluation. Therefore, every (now) within one expression returns the same instant. In system-context mode, a later tool call resolves a new instant. Successful structured results include the resolved context so an answer involving “now” or “today” is auditable.

Convert the instant before asking calendar questions:

; Current instant
(now)

; Current zoned date-time
(with-time-zone (now) (default-time-zone))

; Current local date
(to-date (with-time-zone (now) (default-time-zone)))

The optional default calendar is validated and reported as context, but current operators do not use it for implicit conversion. Temporal values continue to carry their own calendars.

Language overview

Expressions use S-expression syntax:

(operator positional-argument ... :keyword-option value ...)

For example:

(subtract
  2025-12-31
  2025-01-01
  :largest-unit "months")

There must be exactly one top-level expression. Positional arguments must come before keyword options. A semicolon begins a comment that continues through the end of the line:

; Move to the next calendar day
(add
  2025-12-31
  P1D)

The canonical grammar is src/grammar.ebnf, written in ISO/IEC 14977 EBNF. Generated railroad diagrams are available as HTML and Markdown.

Temporal literals

Temporal values are unquoted and self-describing. Constructors and type qualifiers are not used.

| DSL literal | Temporal type | Meaning | |---|---|---| | 2025-01-31 | Temporal.PlainDate | Calendar date without a time or zone | | 2025-06-01T12:00:00Z | Temporal.Instant | Absolute point on the timeline | | 2025-06-01T08:00:00-04:00[America/New_York] | Temporal.ZonedDateTime | Local time, offset, and time-zone identifier | | P1M, PT24H, -P2D | Temporal.Duration | Calendar and/or elapsed-time amount |

The lexer determines a Temporal type from the literal's structure, and the corresponding Temporal from() method validates its value. Classification never depends on the operator receiving the value.

Canonical v1 literal profiles use:

• four-d