@clicktime/mcp-server/README.md

ClickTime MCP Tech Demo for AI agents to interact with ClickTime API

# ClickTime MCP Tech Demo

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](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:

```bash
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](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**:

```bash
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:

```bash
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"`:

```jsonc
{
	"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](https://github.com/clicktime/mcp-server/issues)
- **ClickTime API Docs** – [https://developer.clicktime.com/](https://developer.clicktime.com/)
- **MCP Spec** – [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/) _(or GitHub mirror)_

## License

MIT © ClickTime Team