@clicktime/mcp-server

ClickTime MCP Tech Demo

A Model Context Protocol (MCP) tech demo that lets AI agents – like Claude Desktop – securely interact with ClickTime's time‑tracking, project‑management, and expense‑management APIs.

⚠️ Demo Package Notice: This is a technical demonstration package. ClickTime is not currently providing official support for this package, but we will be updating it constantly as we continue development. Use at your own discretion and expect frequent changes.

What is Model Context Protocol?

MCP is a specification that gives AI tools a secure, structured way to call external services. For ClickTime, it means Claude can:

• Log time – "Log 8 h to Website Redesign → Development today."
• Manage projects & tasks – "What projects am I assigned to?"
• Handle expenses – "Add a $25.50 lunch expense for today."
• Request time off – "Request vacation Dec 24–26."
• Stay in context – Claude remembers your ClickTime workspace between requests.

Prerequisites

Requirement	Notes
Claude Desktop (v≥1.9)	macOS & Windows. Linux users can run the browser version or a VM – the setup script will error on non‑supported OSes.
Node.js (v18 or higher)	Needed to run the MCP server.
ClickTime API Token	Treat it like a password and rotate regularly.

1. Install/Update Claude Desktop

Download from https://claude.ai/download and pick Check for Updates in the menu after install.

2. Check Node.js

Open Terminal / Command Prompt

• macOS Press Cmd + Space, type Terminal, then press Enter
• Windows Press Windows + R, type cmd, then press Enter

In the window that appears, type:

node --version

You should see something like v18.17.0. If you see "command not found" (macOS) or "'node' is not recognized…" (Windows), install the LTS build from https://nodejs.org (v18 or newer).

3. Create / Locate Your ClickTime API Token

1. Log in to ClickTime.
2. Click Your Name → My Preferences → Authentication Token tab.
3. Click Generate (if you haven't already) and Copy the token.

🔒 Keep this token secret – anyone with the string can act as you.

Quick Setup (Recommended) 🚀

Open Terminal / Command Prompt

• macOS Press Cmd + Space, type Terminal, press Enter
• Windows Press Windows + R, type cmd, press Enter

Then copy‑paste the command below (replace <YOUR_CLICKTIME_API_TOKEN> with your real token) and press Enter:

npx @clicktime/mcp-server@latest setup:claude <YOUR_CLICKTIME_API_TOKEN>

That's it! Restart Claude Desktop and start talking to ClickTime.

Privacy tip: Terminal/PowerShell keeps a history of commands you run. If you don't want the line that contains your ClickTime token to stick around, delete it afterwards (history -d on macOS/Linux, Clear-History in PowerShell) or, in bash/zsh, start the command with a space so it isn't recorded.

Alternative: Environment Variable

If you prefer not to include your token in the command line:

export CLICKTIME_API_TOKEN=<YOUR_CLICKTIME_API_TOKEN>
npx @clicktime/mcp-server@latest setup:claude

Manual Setup

If you prefer full control:

1. Open Claude Settings → Developer → Edit Config.
2. Add the clicktime block inside "mcpServers":

{
	"mcpServers": {
		"clicktime": {
			"command": "npx",
			"args": ["@clicktime/mcp-server", "-t", "<YOUR_CLICKTIME_API_TOKEN>"]
		}
	}
}

3. Save, then restart Claude Desktop.

Try It Out!

Examples Claude now understands:

• "Log 8 h to project ABC‑123 → Development today."
• "Show me my time entries for this week."
• "Create a new expense sheet called 'June 2025 – Trade‑show expenses'."
• "Add a $25.50 Lunch expense for today."
• "Request vacation Dec 24–26."
• "What projects do I have access to?"

💡 Receipt expenses – drag an image into Claude, then say "Create an expense from this receipt." Claude will ask for the file path and do the rest.

Core Features

Time Tracking

• Create entries – "Log 8 h to ABC‑123 → Development today."
• View history – "Show my time entries this week."
• Update entries – "Change yesterday's entry to 6 h."

Expense Management

• Quick expenses – "Add $25.50 lunch expense for today."

• Receipt upload

  • Drag‑and‑drop a receipt image into Claude.
  • Or type "Create an expense from /Users/john/receipt.jpg (≤ 2 MB)".

• Expense sheets – "Create expense sheet 'Conference Travel – June 2025'. "

Projects & Time Off

• Projects – "What projects am I assigned to?"
• Time off – "Request vacation Dec 24–26."

Receipt Processing

1. Save the receipt image (JPG, PNG, GIF, BMP, or PDF ≤ 2 MB).

2. Drag & drop the image into Claude Desktop.

3. Ask: "Create an expense from this receipt."

4. When prompted, paste the full file path.

   • macOS: Right‑click + Option → Copy as Pathname
   • Windows: Shift + right‑click → Copy as path

5. Claude extracts the data and creates the expense in ClickTime.

Troubleshooting

Symptom	Fix
"Invalid API token"	Re‑copy token from ClickTime My Preferences.
"ClickTime API token is required"	Provide token as argument: npx @clicktime/mcp-server@latest setup:claude YOUR_TOKEN
"Unsupported platform"	Setup script supports macOS/Windows only. Linux users: configure manually or use VM.
"File too large / unsupported"	Ensure image ≤ 2 MB & is JPG/PNG/GIF/BMP/PDF.
"File not found / ENOENT"	Use the exact path (see path‑copy tips above).
Claude can't see ClickTime tools	Restart Claude; verify mcpServers JSON; check Node v18+.
Permission denied	Confirm your ClickTime account has Time Tracking, Expenses, and/or Time Off modules enabled.
"Failed to connect to ClickTime API"	Verify token and internet connection.

Available Commands

Time Entries

• add_time_entry
• get_recent_time_entries
• update_time_entry
• delete_time_entry

Expenses

• add_expense_item
• add_expense_from_receipt
• create_expense_sheet ✨
• get_my_expense_sheets
• list_my_expense_types

Projects & Tasks

• list_my_projects
• list_my_tasks
• get_project_details

Time Off

• create_time_off_request - Create a time off request (automatically handles both approval/non-approval types)
• remove_time_off - RECOMMENDED: Smart removal that automatically determines whether to delete an entry or cancel a request
• get_time_off - Get time off entries
• get_time_off_requests - List time off requests
• get_time_off_request_details - Get detailed info about a specific request
• get_time_off_request_actions - Get available actions for a request
• get_time_off_balance - Check time off balance
• list_time_off_types - List available time off types

How it works:

• create_time_off_request automatically checks if approval is required and uses the correct endpoint
• remove_time_off automatically determines whether to delete an entry (non-approval) or cancel a request (approval-required)

Support

• GitHub Issues – https://github.com/clicktime/mcp-server/issues
• ClickTime API Docs – https://developer.clicktime.com/
• MCP Spec – https://modelcontextprotocol.io/ (or GitHub mirror)

License

MIT © ClickTime Team