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. Clone and install

git clone https://github.com/cdgrph/tyme-mcp.git
cd tyme-mcp
bun install

3. Configure your MCP client

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "tyme": {
      "command": "bun",
      "args": ["run", "/path/to/tyme-mcp/src/index.ts"]
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "tyme": {
      "command": "bun",
      "args": ["run", "/path/to/tyme-mcp/src/index.ts"]
    }
  }
}

Replace /path/to/tyme-mcp with the actual path where you cloned the repository.

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

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)
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_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_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 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