⏱️ 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

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

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

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

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

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

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

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

🔑 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).

Projects

Time Entries

Teams

Reports

🎯 Available Prompts

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

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

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

{
  "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