TimeIQ Model Context Protocol (MCP) Server

A production-ready, fully anonymized Model Context Protocol (MCP) server for TimeIQ time tracking. It provides a standard integration pattern that allows LLM agents (like Claude Desktop, Cursor, or custom gateway agents running on Hermes) to view and manage time entries, projects, clients, reports, invoices, expenses, services, and timesheets via a secure stdio transport.

🚀 Key Features

• Anonymized & Secure by Design: Zero hardcoded credentials or branding (no mentions of internal subdomains, private domains, or local credentials).

• Interactive Setup Wizard: Run npx timeiq-mcp setup to automatically generate all env maps, define Slack admins/coworkers interactively, and get copy-paste ready config snippets.

• Safe-by-Default (Dry-Run): Defaults to TIMEIQ_DRY_RUN=true to prevent agents from inadvertently creating, modifying, or deleting entries. All modification requests describe the intended action without executing it.

• Bulk Action Gate: Forces safety confirmation for multi-record operations.

• Complete Reverse-Engineered Coverage: Exposes 50+ tools and 3 read-only resources spanning the entire TimeIQ SPA API.

• In-Memory Session Security: Employs an in-memory session cookie jar (zero tokens or cookies are persisted to disk).

• Robust Timezone & Input Handling: Strict date validation (prevents JS calendar rollover bugs like 2026-02-30 silently resolving to March 2nd) and automatic snake_case slugifiers that convert names with German diacritics and umlauts (e.g., ä → ae, ß → ss).

• Slack Member ID Mapping & Security: Supports the TIMEIQ_SLACK_MAP environment variable to securely map Slack user IDs directly to individual coworker emails, ensuring hard user-level data ownership and action boundaries.

Related MCP server: Calq MCP

🤖 AI Agent Compatibility & Query Examples

🧠 Primarily Built for Hermes (Zweibot)

This MCP setup was primarily designed for integration with the Hermes agent (Zweibot). It runs flawlessly on your remote VPS container and enables frictionless, real-time time tracking and project management directly via Slack.

Universal MCP Compatibility: Because this server fully conforms to the Model Context Protocol (MCP) specification, any other AI assistant or client (such as Claude Desktop, Cursor, Cline, Windsurf, or Cloud Coworker) can integrate and work with it immediately out of the box with zero custom adjustments.

💬 Practical Query Examples (Prompts) for the AI

Here are concrete, real-world examples of natural language prompts you can give to your AI coworker (e.g. Hermes in Slack or Claude in Claude Desktop/Cursor), along with the corresponding MCP tools mapped under the hood:

1. Time Tracking

• Query: “Please book 15 minutes today on the project '[Client Name] - SEO monatlich' with the description: Developing content strategy.”

  • MCP Tool: timeiq_time_create (using start_time and end_time or duration style).

• Query: “I worked on the website today from 10:00 AM to 11:30 AM. Please log that time.”

  • MCP Tool: timeiq_time_create (automatically parses and converts the duration to 90 minutes).

• Query: “Delete my time entry with the ID 44088.”

  • MCP Tool: timeiq_time_delete.

2. Running Stopwatches (Timer)

• Query: “Start a stopwatch for the 'Marketing Campaign' project and set the topic to 'Create social media post'.”

  • MCP Tool: timeiq_timer_start.

• Query: “How long has my current stopwatch been running and what am I working on?”

  • MCP Tool: timeiq_timer_get.

• Query: “Change the notes of my active timer to 'Review round with the client'.”

  • MCP Tool: timeiq_timer_update (routes a flat PUT payload to the correct /actions/updateTimeEntry API endpoint).

• Query: “I'm finished, please stop the stopwatch and save the time.”

  • MCP Tool: timeiq_timer_stop (stops the running timer and persists the time entry).

• Query: “Cancel the active stopwatch and discard the time.”

  • MCP Tool: timeiq_timer_cancel (deletes the running stopwatch without creating any time entry).

3. Managing Projects & Clients

• Query: “Show me a list of all our active projects.”

  • MCP Tool: timeiq_project_list (filtered by active).

• Query: “Can you please archive the 'Insurance Directory' project?”

  • MCP Tool: timeiq_project_archive (safely looks up the project ID and archives it via bulk-routing).

• Query: “Create a new client named 'ACME GmbH' and set up a project called 'Web Design 2026' for them.”

  • MCP Tools: timeiq_client_create followed by timeiq_project_create.

4. Reports & Analysis

• Query: “Generate a report for this week and show me the total hours booked.”

  • MCP Tool: timeiq_report_standard (returns high-level summary KPIs).

• Query: “Search for all my time entries logged today.”

  • MCP Tool: timeiq_report_search_time (executes search utilizing double-nested parameters).

• Query: “Are there any coworkers who have not completed their required hours this week?”

  • MCP Tool: timeiq_report_missing_time.

5. Invoices & Expenses

• Query: “Show me all invoices for '[Client Name]' from this year.”

  • MCP Tool: timeiq_invoice_list_for_client.

• Query: “Log a new expense of 45 € for 'Train Ticket' on the project 'SEO monatlich'.”

  • MCP Tool: timeiq_expense_create.

• Query: “Mark invoice number RE-2026-004 as fully paid.”

  • MCP Tool: timeiq_invoice_mark_paid (resolved dynamically using timeiq_invoice_get_by_number).

6. Timesheets & System Info

• Query: “Submit my timesheet for the current period for approval.”

  • MCP Tool: timeiq_timesheet_submit (automatically fetches the active period and submits it).

• Query: “Who am I in TimeIQ and what are my permissions?”

  • MCP Tool: timeiq_whoami (retrieves full profile details from /api/people/me).

🛠️ Installation & Setup

Requirements

• Node.js >= 20.0.0

⚡ Quick Interactive Setup Wizard (Recommended)

To configure the server, map Slack User IDs to emails, and generate config blocks instantly, run the zero-dependency interactive setup CLI wizard:

npm run setup

or directly via:

npx timeiq-mcp setup

The wizard will guide you through:

1. Entering your TimeIQ Tenant subdomain, email, and password.

2. Specifying the Admin Slack User ID (which maps to your admin email).

3. Sequentially adding as many coworker Slack User IDs and corresponding TimeIQ Emails as you want.

4. Setting the default safety mode (Dry-run).

Once completed, it will automatically:

• Create/update a local .env file in the working directory.

• Render copy-paste-ready config blocks for both Claude Desktop and Hermes (config.yaml).

• Display a clear role/user mapping table for verification.

1. Environment Variables

Configure the following environment variables. The server will validate them on startup using Zod:

💻 Configuration

A. Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "timeiq-mcp": {
      "command": "npx",
      "args": ["-y", "timeiq-mcp"],
      "env": {
        "TIMEIQ_TENANT": "your-tenant",
        "TIMEIQ_EMAIL": "your-email@example.com",
        "TIMEIQ_PASSWORD": "your-password",
        "TIMEIQ_DRY_RUN": "true"
      }
    }
  }
}

B. Cursor

1. Go to Settings > Features > MCP.

2. Click + Add New MCP Server.

3. Fill in the details:

   • Name: timeiq-mcp

   • Type: command

   • Command:

     env TIMEIQ_TENANT="your-tenant" TIMEIQ_EMAIL="your-email@example.com" TIMEIQ_PASSWORD="your-password" TIMEIQ_DRY_RUN="true" npx -y timeiq-mcp

C. Hermes / Remote Gateway (Honcho / VPS)

To integrate the server with remote gateway bots, register the tool inside the bots' local config.yaml and boot:

mcp:
  servers:
    timeiq-mcp:
      command: "npx"
      args: ["-y", "timeiq-mcp"]
      env:
        TIMEIQ_TENANT: "your-tenant"
        TIMEIQ_EMAIL: "admin-account@example.com"
        TIMEIQ_PASSWORD: "secure-password"
        TIMEIQ_DRY_RUN: "false" # Set to false to allow actual actions
        TIMEIQ_SLACK_MAP: '{"U12345678": "cara@example.com", "U87654321": "emily@example.com"}'

🛠️ Exposed MCP Tools

The server exposes modular tools mapped across 10 distinct domains:

📅 1. Time & Timers (time.ts)

• timeiq_time_list_me: List acting user's time entries in a date range. Defaults to today.

• timeiq_time_list_person: Admin only. Retrieve time entries for another user.

• timeiq_time_create: Create a time entry (supports both start/end time and duration style).

• timeiq_time_create_overbook: Create a time entry with budget warnings.

• timeiq_time_update: Update a single time entry using automatic changeset comparison.

• timeiq_time_delete: Delete a single time entry.

• timeiq_time_delete_many: Delete multiple time entries by ID list.

• timeiq_time_update_many: Apply bulk updates to a list of time entries.

• timeiq_time_batch: Week-grid-style batch updates.

• timeiq_timer_get: Get currently running stopwatch.

• timeiq_timer_start: Start a new running timer.

• timeiq_timer_stop: Stop running timer and convert to a time entry.

• timeiq_timer_cancel: Cancel active timer.

• timeiq_timer_update: Update active timer notes/project.

• timeiq_timer_update_entry: Update underlying entry of active timer.

🏢 2. Projects & Clients (projects.ts)

• timeiq_project_list: List projects. Can filter by active, archived, managed, or managed_archived.

• timeiq_project_get: Get single project details by slug.

• timeiq_project_create: Create a project (auto-slugifies names).

• timeiq_project_update: Update project attributes.

• timeiq_project_update_many: Update multiple projects in one call.

• timeiq_project_delete: Delete a project.

• timeiq_project_archive: Archive a project.

• timeiq_project_activate: Re-activate an archived project.

• timeiq_client_list: List clients. Can filter by active, archived, managed, or managed_archived.

• timeiq_client_get: Get client details by slug.

• timeiq_client_create: Create client.

• timeiq_client_update: Update client.

• timeiq_client_delete: Delete client.

• timeiq_client_archive: Archive a client.

• timeiq_client_activate: Re-activate an archived client.

👥 3. People & Capacity (people.ts)

• timeiq_whoami: Get profile and settings of currently authenticated acting user.

• timeiq_person_list: List team members. Can filter by active, archived, managed, or managed_archived.

• timeiq_person_get: Get single team member by slug.

• timeiq_person_create: Create new person (Admin only).

• timeiq_person_update: Update person details (Admin only).

• timeiq_person_delete: Delete a person (Admin only).

• timeiq_person_archive: Archive a coworker.

• timeiq_person_activate: Re-activate a coworker.

• timeiq_person_update_preferences: Update own preferences.

• timeiq_person_required_time_get: Get capacity settings for a person.

• timeiq_person_required_time_set: Set capacity values for a person.

📊 4. Reports (reports.ts)

• timeiq_report_standard: Overview report (summary card data).

• timeiq_report_standard_time: Standard report time-tab entries.

• timeiq_report_standard_expenses: Standard report expenses.

• timeiq_report_time: Time summary totals & group-by breakdowns.

• timeiq_report_time_detail: Detailed time-entry report list.

• timeiq_report_expenses: Summary expense report.

• timeiq_report_expenses_detail: Detailed expense report list.

• timeiq_report_classic: Classic summary report.

• timeiq_report_classic_time: Classic time report.

• timeiq_report_custom: Custom report with custom parameters.

• timeiq_report_period: Period-aligned timesheet report.

• timeiq_report_payroll: Payroll summaries for staff.

• timeiq_report_recent_activity: Feed of latest changes.

• timeiq_report_missing_time: Identify people missing capacity entries.

• timeiq_report_incomplete_time: Identify people with incomplete times.

• timeiq_report_search_time: Search across time entries.

• timeiq_report_search_expenses: Search across expense entries.

💼 5. Expenses (expenses.ts)

• timeiq_expense_list_me: List expense entries for the acting user.

• timeiq_expense_list_person: List expense entries for another user.

• timeiq_expense_create: Log new expense (travel, software, etc.).

• timeiq_expense_update: Update logged expense.

• timeiq_expense_delete: Delete expense.

• timeiq_expense_delete_many: Delete multiple expenses.

• timeiq_expense_update_many: Apply updates to multiple expenses.

• timeiq_expense_type_list: List expense types.

• timeiq_expense_type_get: Get single expense type by slug.

• timeiq_expense_type_create: Create expense type.

• timeiq_expense_type_update: Update expense type.

• timeiq_expense_type_delete: Delete expense type.

• timeiq_expense_type_archive: Archive an expense type.

• timeiq_expense_type_activate: Re-activate an expense type.

• timeiq_expense_category_list: List expense categories.

• timeiq_expense_category_create: Create expense category.

• timeiq_expense_category_update: Update expense category.

• timeiq_expense_category_delete: Delete expense category.

• timeiq_expense_category_archive: Archive an expense category.

• timeiq_expense_category_activate: Re-activate an expense category.

🏷️ 6. Services (services.ts)

• timeiq_service_list: List billable services (tasks).

• timeiq_service_create: Create billable service.

• timeiq_service_update: Update service.

• timeiq_service_delete: Delete service.

• timeiq_service_archive: Archive a service.

• timeiq_service_activate: Re-activate a service.

• timeiq_service_category_list: List service categories.

• timeiq_service_category_create: Create service category.

• timeiq_service_category_update: Update service category.

• timeiq_service_category_delete: Delete service category.

• timeiq_service_category_archive: Archive a service category.

• timeiq_service_category_activate: Re-activate a service category.

🕒 7. Timesheets & Approvals (timesheets.ts)

• timeiq_timesheet_period_list: List all timesheet periods.

• timeiq_timesheet_period_by_date: Get the timesheet period covering a specific date.

• timeiq_timesheet_period_get: Get details for a single timesheet period by ID.

• timeiq_timesheet_list: List timesheets for the acting user.

• timeiq_timesheet_get: Get details for a single timesheet by ID.

• timeiq_timesheet_by_date: Get the timesheet covering a specific date.

• timeiq_timesheet_with_issues: List timesheets flagged with issues.

• timeiq_timesheet_neighbors: Fetch neighbor timesheets.

• timeiq_timesheet_submit: Submit a timesheet for review and approval.

• timeiq_timesheet_approve: Approve a submitted timesheet (Manager/Admin only).

• timeiq_timesheet_decline: Decline/reject a submitted timesheet (Manager/Admin only).

• timeiq_timesheet_send_reminder: Trigger a missing timesheet submission email reminder.

🧾 8. Invoices (invoices.ts)

• timeiq_invoice_list: List all invoices, optionally filtered by date range.

• timeiq_invoice_list_for_client: List all invoices for a specific client.

• timeiq_invoice_get: Get details of a single invoice by its ID.

• timeiq_invoice_get_by_number: Get a single invoice by its alphanumeric invoice number.

• timeiq_invoice_create: Create a new draft invoice.

• timeiq_invoice_update: Update an invoice (e.g. details, dates, comments).

• timeiq_invoice_delete: Delete an existing invoice by ID.

• timeiq_invoice_mark_paid: Mark an invoice status as fully paid.

• timeiq_invoice_mark_unpaid: Mark a paid or drafted invoice status as unpaid.

• timeiq_invoice_mark_written_off: Mark an invoice status as written-off.

• timeiq_invoice_send: Trigger the invoice-send email.

• timeiq_invoice_export: Get invoice export/PDF compile details.

• timeiq_lineitem_add: Add a new line item details row to an existing invoice.

• timeiq_lineitem_update: Update a single line item details row on an invoice.

• timeiq_lineitem_delete: Remove a line item details row from an invoice.

🔔 9. Notifications & Reminders (notifications.ts)

• timeiq_notifications_list: Fetch active notifications.

• timeiq_notifications_dismiss: Dismiss notification by ID.

• timeiq_notifications_remind_missing: Trigger missing-time email reminder to a user.

• timeiq_notifications_remind_timesheet: Trigger timesheet-approval reminder.

⚙️ 10. System Settings (settings.ts)

• timeiq_settings_get: Get tenant-wide preferences.

• timeiq_settings_update: Update system configuration parameters.

• timeiq_settings_timezones: Retrieve active timezone choices.

📦 Exposed Resources

The server exposes three read-only resources through standard URI schemes:

1. timeiq://schemas: Dynamically dumps complete JSON schemas of all primary entities (Person, Client, Project, TimeEntry, Invoice, etc.) derived from strict Zod schemas.

2. timeiq://endpoints: The entire reverse-engineered specification of the TimeIQ HTTP endpoints, allowing the LLM to inspect route constraints and exact payloads.

3. timeiq://me: A snapshot of the currently acting user's profile and permission configuration (cached for 60 seconds).

🔒 Safety & Simulations

When running in Dry-Run mode (TIMEIQ_DRY_RUN=true), any mutating operation returns a simulated response structured identically to the actual API response:

{
  "dry_run": true,
  "request": {
    "method": "POST",
    "path": "/api/time",
    "body": {
      "date": "2026-05-29",
      "project_id": 2070,
      "duration": 60,
      "notes": "Testing the MCP Server safely"
    }
  }
}

🧪 Development

Install dependencies

npm install

Run tests

The test suite utilizes Vitest to validate strict dates, slugifiers, and partial changeset generation:

npm run test

Compile TypeScript

npm run build

📄 License

This project is licensed under the MIT License.