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

| Tool | Description | |------|-------------| | start_timer | Start a timer for a task | | stop_timer | Stop a timer for a task | | get_running_timers | List currently running timers |

Data Retrieval

| Tool | Description | |------|-------------| | list_categories | List all categories | | list_projects | List projects (optionally filtered by category) | | get_project_detail | Get detailed project information | | list_tasks | List tasks in a project | | list_subtasks | List subtasks of a task | | get_task_detail | Get detailed task information | | get_selected_object | Get the currently selected item in Tyme UI | | get_task_records | Search time records by date range and filters | | get_record_detail | Get detailed record information |

CRUD Operations

| Tool | Description | |------|-------------| | create_category | Create a new category | | update_category | Update a category | | delete_category | Delete a category | | create_project | Create a new project | | update_project | Update project properties | | delete_project | Delete a project | | create_task | Create a new task | | update_task | Update task properties | | delete_task | Delete a task | | create_subtask | Create a new subtask | | update_subtask | Update subtask properties | | delete_subtask | Delete a subtask | | create_record | Create a time record | | update_record | Update a time record | | delete_record | Delete a time record |

Reports

| Tool | Description | |------|-------------| | get_daily_summary | Work summary for a specific day | | get_range_summary | Work summary over a date range, grouped by project |

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