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

• Project & task management — List, create, update, and delete projects and tasks

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

• 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

• 22 tools covering the full Tyme workflow

Requirements

• macOS

• Tyme 3 installed and running

• Bun runtime

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"]
    }
  }
}

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

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 write operations — reliable object creation and manipulation

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

Tech Stack

• Bun — TypeScript runtime

• @modelcontextprotocol/sdk — MCP server SDK

• Zod — Input validation

• AppleScript / JXA — macOS automation

License

MIT