tyme-mcp

An MCP (Model Context Protocol) server that connects AI assistants to Tyme, the macOS time tracking app. Control timers, manage projects and tasks, search time records, and generate reports — all through natural language.

Features

• Timer control — Start, stop, and check running timers

• Category, project, task & subtask management — List, create, update, and delete Tyme objects (projects and tasks also support detailed lookup)

• Time record search — Query records by date range, project, task, type, and more

• Mileage tracking — Configure per-kilometer rates and record traveled distance

• Reports — Daily summaries and date-range reports grouped by project

• Native macOS integration — Communicates directly with Tyme via AppleScript/JXA. No API keys, no cloud dependency, works offline

• 29 tools covering the full Tyme workflow

Requirements

• macOS

• Tyme 3 installed and running

• Bun runtime — Bun is required because the package runs TypeScript directly. Use bunx tyme-mcp; npx tyme-mcp is not supported.

Setup

1. Install Bun (if not installed)

curl -fsSL https://bun.sh/install | bash

2. Configure your MCP client

Claude Code

claude mcp add tyme -- bunx tyme-mcp

Or add to your .mcp.json:

{
  "mcpServers": {
    "tyme": {
      "command": "bunx",
      "args": ["tyme-mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tyme": {
      "command": "bunx",
      "args": ["tyme-mcp"]
    }
  }
}

3. Launch Tyme

Make sure Tyme is running before using the MCP server. The server communicates with Tyme through macOS scripting, so Tyme must be open.

Tools

Date-only inputs are interpreted in the server's local timezone. For date ranges, endDate is inclusive through the end of the specified day.

Timer Operations

Data Retrieval

CRUD Operations

Reports

Usage Examples

Once configured, you can interact with Tyme using natural language:

• "Show me my projects" — lists all Tyme projects

• "What timers are running?" — checks active timers

• "Start tracking time on task X" — starts a timer

• "How much did I work this week?" — generates a summary report

• "Create a new task called 'Design review' in project Y" — creates a task

How It Works

AI Assistant → MCP Protocol → tyme-mcp → osascript (AppleScript/JXA) → Tyme.app

The server uses two scripting approaches:

• JXA (JavaScript for Automation) for read operations — returns structured JSON

• AppleScript for object creation/deletion, JXA for property updates

All user inputs are sanitized before interpolation into scripts to prevent injection.

Development

# Run the server directly
bun run src/index.ts

# Watch mode
bun run dev

# Type-check the TypeScript source (CI gate)
bun run typecheck

# Run unit tests (Tyme is not required)
bun test

# Run the E2E smoke suite (requires Tyme running locally)
# Test data is cleaned up automatically, including after failures.
bun run smoke

Tech Stack

• Bun — TypeScript runtime

• @modelcontextprotocol/sdk — MCP server SDK

• Zod — Input validation

• AppleScript / JXA — macOS automation

License

MIT