⏱️ Timing MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to the Timing API for time tracking, project management, and productivity insights.

[!warning] This repository is not affiliated with Timing. It is an independent project created to enhance the functionality of the Timing application.

[!note] This is a fork of tomoyanakano/timing-mcp-server, extended with additional capabilities, prompts support, and production-ready structure.

⚡ Quick Start

npx -y @a-und-b/timing-mcp

That's it! The server will start and be ready to connect to your MCP client.

🚀 Installation

Prerequisites

• Node.js ≥ 18.0.0
• Timing account with API access
• Timing API key (Get your API key here)

MCP Client Integration

Add to your Claude Desktop claude_desktop_config.json file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "timing": {
      "command": "npx",
      "args": ["-y", "@a-und-b/timing-mcp"],
      "env": {
        "TIMING_API_KEY": "your-timing-api-key"
      }
    }
  }
}

Add to your Cursor settings:

MacOS: ~/Library/Application Support/Cursor/User/settings.json
Windows: %APPDATA%\Cursor\User\settings.json
Linux: ~/.config/Cursor/User/settings.json

{
  "mcpServers": {
    "timing": {
      "command": "npx",
      "args": ["-y", "@a-und-b/timing-mcp"],
      "env": {
        "TIMING_API_KEY": "your-timing-api-key"
      }
    }
  }
}

Add to your Windsurf MCP configuration:

{
   "mcpServers": {
      "timing": {
         "command": "npx",
         "args": ["-y", "@a-und-b/timing-mcp"],
         "env": {
            "TIMING_API_KEY": "your-timing-api-key"
         }
      }
   }
}

Add the MCP server to Claude Code:

claude mcp add -e TIMING_API_KEY="your-timing-api-key" timing -- npx -y @a-und-b/timing-mcp

Configure Gemini CLI with MCP support:

{
   "mcpServers": {
      "timing": {
         "command": "npx",
         "args": ["-y", "@a-und-b/timing-mcp"],
         "env": {
            "TIMING_API_KEY": "your-timing-api-key"
         }
      }
   }
}

1. Go to Kiro > MCP Servers
2. Add new MCP server by clicking + Add
3. Paste the configuration below:

{
  "mcpServers": {
    "timing": {
    "command": "npx",
    "args": [
      "-y",
      "@a-und-b/timing-mcp"
    ],
    "env": {
       "TIMING_API_KEY": "your-timing-api-key"
    },
    "disabled": false,
    "autoApprove": []
    }
  }
}

1. Click Save to apply changes

1. Go to Program (right side) > Install > Edit mcp.json
2. Paste the configuration below:

{
  "mcpServers": {
    "timing": {
      "command": "npx",
      "args": ["-y", "@a-und-b/timing-mcp"],
       "env": {
          "TIMING_API_KEY": "your-timing-api-key"
       }
    }
  }
}

1. Click Save to apply changes
2. Toggle MCP server on/off from the right hand side (under Program) or by clicking the plug icon at the bottom of the chat box

🔑 Timing API Setup

Getting Your API Key

1. Log into your Timing account
2. Navigate to API settings:
   • Go to Integrations → API Keys
   • Or visit: https://web.timingapp.com/integrations/tokens
3. Generate a new API key (if you don't have one)
4. Copy the API key and add it to your MCP client configuration

Environment Variables

You can set environment variables in several ways:

Option 1: System Environment Variables

export TIMING_API_KEY="your-timing-api-key"

Option 2: .env File (for local development)

TIMING_API_KEY=your-timing-api-key

Option 3: MCP Client Configuration (recommended) Use the env section in your MCP client configuration as shown above.

🛠️ Available Tools

Local Database

[!note] This feature only works when the MCP server is running on the same machine as the Timing app (macOS).

Tool	Description	Parameters
timing_get_granular_app_activity	Get granular usage (window titles, paths) from local DB	from, to (date strings or relative terms like 'today', 'yesterday'), limit

Projects

Tool	Description	Parameters
timing_list_projects	List all projects with optional filtering	title, hideArchived, teamId (all optional)
timing_list_projects_hierarchy	Get hierarchical project structure	teamId (optional)
timing_project	Get project details	id
timing_create_project	Create a new project	title, parent, color, notes, productivityScore, etc.
timing_update_project	Update an existing project	projectId, various optional fields
timing_delete_project	Delete a project	projectId

Time Entries

Tool	Description	Parameters
timing_list_time_entries	List time entries with filtering	startDateMin, startDateMax, projects, searchQuery, etc.
timing_time_entry	Get time entry details	id
timing_create_time_entry	Create a new time entry	project, title, startDate, endDate, notes, billingStatus
timing_update_time_entry	Update an existing time entry	timeEntryId, various optional fields
timing_delete_time_entry	Delete a time entry	timeEntryId
timing_start_time_entry	Start a new timer	project, title, startDate, notes
timing_stop_time_entry	Stop the current timer	(no parameters)
timing_batch_update_time_entries	Batch update multiple time entries	timeEntryIds, billingStatus, customFields

Teams

Tool	Description	Parameters
timing_list_teams	List all teams	(no parameters)
timing_team	Get team details	id

Reports

Tool	Description	Parameters
generate_timing_report	Generate comprehensive report	startDateMin, startDateMax, projects, columns, etc.

🎯 Available Prompts

The Timing MCP server provides 7 intelligent prompts that orchestrate multiple tools to deliver comprehensive insights:

Prompt	Description	Key Parameters
weekly_time_report	Generates detailed weekly time tracking report with project breakdown	week_start, include_project_breakdown
project_time_analysis	Analyzes time spent across projects with insights	project_ids, time_period
productivity_insights	Analyzes productivity patterns and provides recommendations	analysis_period, focus_area
billing_summary	Generates billing status summary with revenue insights	start_date, end_date, include_status_breakdown
time_entry_audit	Audits time entries for completeness and accuracy	start_date, end_date, check_running_entries
project_hierarchy_overview	Visualizes project structure and time distribution	team_id, include_archived
monthly_time_summary	Creates comprehensive monthly time summary with trends	month, year, include_comparisons

Prompt Examples

Weekly Time Report:

{
  "name": "weekly_time_report",
  "arguments": {
    "week_start": "2024-01-15",
    "include_project_breakdown": true
  }
}

Project Time Analysis:

{
  "name": "project_time_analysis",
  "arguments": {
    "project_ids": "1,2,3",
    "time_period": "last_month"
  }
}

Billing Summary:

{
  "name": "billing_summary",
  "arguments": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "include_status_breakdown": true
  }
}

📝 Tool Examples

Get Granular Activity

{
  "name": "timing_get_granular_app_activity",
  "arguments": {
    "from": "yesterday",
    "to": "today",
    "limit": 10
  }
}

List Projects

{
  "name": "timing_list_projects",
  "arguments": {
    "hideArchived": true
  }
}

Create Project

{
  "name": "timing_create_project",
  "arguments": {
    "title": "Website Redesign",
    "color": "#FF0000",
    "productivityScore": 1,
    "notes": "Main client project"
  }
}

List Time Entries

{
  "name": "timing_list_time_entries",
  "arguments": {
    "startDateMin": "2024-01-01T00:00:00+00:00",
    "startDateMax": "2024-01-31T23:59:59+00:00",
    "includeProjectData": true
  }
}

Create Time Entry

{
  "name": "timing_create_time_entry",
  "arguments": {
    "project": "/projects/1",
    "title": "Frontend Development",
    "startDate": "2024-01-15T09:00:00+00:00",
    "endDate": "2024-01-15T17:00:00+00:00",
    "notes": "Implemented new features",
    "billingStatus": "billable"
  }
}

Start Timer

{
  "name": "timing_start_time_entry",
  "arguments": {
    "project": "/projects/1",
    "title": "Working on feature",
    "notes": "Starting development"
  }
}

Generate Report

{
  "name": "generate_timing_report",
  "arguments": {
    "startDateMin": "2024-01-01",
    "startDateMax": "2024-01-31",
    "columns": ["title", "project", "duration"],
    "timespanGroupingMode": "day"
  }
}

🔧 Advanced Configuration

If you want to run from source:

git clone https://github.com/a-und-b/timing-mcp.git
cd timing-mcp
npm install
npm run build
npm start

Then configure your MCP client to use the local path:

{
  "mcpServers": {
    "timing": {
      "command": "node",
      "args": ["/path/to/timing-mcp/dist/index.js"],
      "env": {
        "TIMING_API_KEY": "your-timing-api-key"
      }
    }
  }
}

FROM node:18-alpine
WORKDIR /app
RUN npm install -g @a-und-b/timing-mcp
ENV TIMING_API_KEY=""
CMD ["timing-mcp"]

🔍 Troubleshooting

Common Issues

❌ Authentication Error:

TIMING_API_KEY environment variable is not set

• Verify your API key is correct
• Check if the API key is properly set in environment variables
• Ensure the key hasn't expired

❌ Node.js Version Error:

This package requires Node.js >= 18.0.0

• Update Node.js to version 18 or higher
• Check your version: node --version

❌ npx Connection Issues:

Error: Cannot find module '@a-und-b/timing-mcp'

• Ensure you have internet connection
• Try: npx --yes @a-und-b/timing-mcp
• Clear npx cache: npx clear-npx-cache

❌ MCP Client Not Finding Tools:

• Restart your MCP client after configuration changes
• Check that environment variables are properly set
• Verify JSON configuration syntax is correct

Debug Mode

For debugging, you can run the server with additional logging:

NODE_ENV=development npx -y @a-und-b/timing-mcp

Testing Connection

You can test the server manually:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npx -y @a-und-b/timing-mcp

🌟 Features

• 🖥️ Local Data Access: Direct access to local SQLite database for granular activity data (window titles, file paths)
• ✅ Full CRUD Support: Create, read, update, and delete across projects and time entries
• 🔄 Automatic Validation: Input validation using Zod schemas
• 📊 Comprehensive Reports: Generate detailed reports with flexible filtering
• ⏱️ Timer Control: Start and stop timers for time tracking
• 💰 Billing Status: Track billing status (billable, not_billable, billed, paid)
• 🏗️ Project Hierarchy: Access hierarchical project structures
• 🧩 Comprehensive Tools: 18 specialized tools for different use cases
• 🎯 Intelligent Prompts: 7 AI-powered prompts for complex analysis and insights
• 🌐 Multi-Client Support: Works with all major MCP clients
• 📝 Custom Fields: Support for custom fields on projects and time entries

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

This project is a fork of tomoyanakano/timing-mcp-server, extended with comprehensive capabilities, prompts support, and production-ready structure.

🆘 Support

• Timing API Issues: Timing API Documentation
• MCP Protocol: MCP Documentation
• This Package: GitHub Issues