solidtime-mcp/README.md

# solidtime-mcp-server

[![CI](https://github.com/SwamiRama/solidtime-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/SwamiRama/solidtime-mcp-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm](https://img.shields.io/npm/v/solidtime-mcp-server)](https://www.npmjs.com/package/solidtime-mcp-server)

Cloud-hosted MCP server for [SolidTime](https://www.solidtime.io/) — the open-source time tracking app. Start/stop timers, manage time entries, projects, clients, tags, tasks, members, invitations, and organizations directly from Claude, Cursor, or any MCP-compatible client.

## Features

- **42 tools** covering time entries, projects, clients, tags, tasks, members, organizations, project members, and invitations
- **Cloud-hosted** — no local installation required, connect via URL from any MCP client
- **Per-user credentials** — API token and settings passed through MCP client headers
- **Start/stop timers** with automatic active-timer detection
- **Batch operations** — update or delete multiple time entries at once
- **Aggregated reports** grouped by day, week, month, year, project, client, task, user, billable, description, or tag — with optional sub-grouping
- **Member & invitation management** — list, update, remove members; send and manage invitations
- **Organization management** — view and update organization settings
- **Auto member_id resolution** — no manual configuration needed
- **Timezone support** — display and accept times in your local timezone
- **Built-in MCP instructions** — the server provides contextual guidance to AI clients for optimal tool usage
- **Session management** — per-user sessions with automatic 30-minute expiry
- **Docker-ready** — multi-stage Dockerfile for easy deployment
- **Actionable error messages** — every error tells you what to do next
- **Zero external dependencies** beyond the MCP SDK (uses native `fetch`)
- Works with self-hosted SolidTime instances and the hosted version

## Quick Start

The server is hosted in the cloud — just point your MCP client to the server URL and pass your SolidTime credentials as headers.

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "solidtime": {
      "url": "https://your-server.example.com/mcp",
      "headers": {
        "x-solidtime-api-token": "your-token-here",
        "x-solidtime-organization-id": "your-org-uuid-here",
        "x-solidtime-api-url": "https://your-instance.example.com",
        "x-solidtime-timezone": "Europe/Berlin"
      }
    }
  }
}
```

### Claude Code

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "solidtime": {
      "url": "https://your-server.example.com/mcp",
      "headers": {
        "x-solidtime-api-token": "your-token-here",
        "x-solidtime-organization-id": "your-org-uuid-here",
        "x-solidtime-api-url": "https://your-instance.example.com",
        "x-solidtime-timezone": "Europe/Berlin"
      }
    }
  }
}
```

### Cursor / Windsurf / Other MCP Clients

Use the streamable HTTP transport with these settings:

| Setting | Value |
|---------|-------|
| **URL** | `https://your-server.example.com/mcp` |
| **Transport** | Streamable HTTP |

Pass the headers below in your client's MCP configuration.

### Headers

| Header | Required | Description |
|--------|----------|-------------|
| `x-solidtime-api-token` | Yes | Your SolidTime API token |
| `x-solidtime-organization-id` | No | Your organization UUID (auto-selected if you belong to only one) |
| `x-solidtime-api-url` | No | Base URL for self-hosted SolidTime instances (default: `https://app.solidtime.io`) |
| `x-solidtime-timezone` | No | IANA timezone name (e.g. `Europe/Berlin`, `America/New_York`). Without this, all times are in UTC |

Get your API token from **SolidTime > Settings > API**.

## Server Deployment

### Docker

```bash
docker build -t solidtime-mcp-server .
docker run -d \
  -e PORT=3045 \
  -e SOLIDTIME_API_URL=https://app.solidtime.io \
  -p 3045:3045 \
  solidtime-mcp-server
```

### Dokploy / Docker Swarm

Create an **Application** (not Compose) in Dokploy pointing to your Git repo. Dokploy will build using the Dockerfile and deploy as a Swarm service. Configure in the Dokploy dashboard:

- **Domain**: your desired hostname, pointing to port `3045`
- **Environment variables**: `PORT=3045` and `SOLIDTIME_API_URL`

> **Note**: Compose-type deployments use `docker compose up` which creates plain containers. If your Dokploy instance runs Traefik with Docker Swarm, use Application type so Traefik's Swarm provider can discover the service.

### Server Environment Variables

These are set on the server, not by MCP clients:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PORT` | No | `3045` | HTTP server port |
| `SOLIDTIME_API_URL` | No | `https://app.solidtime.io` | Default SolidTime API URL (clients can override via header) |

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/mcp` | Initialize session / send MCP messages |
| `GET` | `/mcp` | SSE stream listener (requires `mcp-session-id` header) |
| `DELETE` | `/mcp` | Close session |
| `GET` | `/health` | Health check (returns status and active session count) |

Sessions expire automatically after 30 minutes of inactivity.

## Tools

### Time Entries (10 tools)

| Tool | Description |
|------|-------------|
| `solidtime_start_timer` | Start a running timer (checks for existing active timer first) |
| `solidtime_stop_timer` | Stop the active timer |
| `solidtime_get_active_timer` | Get the currently running timer |
| `solidtime_list_time_entries` | List entries with filters (date range, project, client, tags, billable) |
| `solidtime_create_time_entry` | Create a completed entry with start and end times |
| `solidtime_update_time_entry` | Update any field on an existing entry |
| `solidtime_delete_time_entry` | Permanently delete an entry |
| `solidtime_update_multiple_time_entries` | Update multiple entries at once |
| `solidtime_delete_multiple_time_entries` | Delete multiple entries at once |
| `solidtime_get_time_entry_report` | Aggregated report by day/week/month/year/project/client/task/user/billable/description/tag with optional sub-grouping |

### Projects (4 tools)

| Tool | Description |
|------|-------------|
| `solidtime_list_projects` | List all projects (filter by archived status) |
| `solidtime_create_project` | Create a project with name, color, billable rate |
| `solidtime_update_project` | Update project fields |
| `solidtime_delete_project` | Permanently delete a project |

### Clients (4 tools)

| Tool | Description |
|------|-------------|
| `solidtime_list_clients` | List all clients (filter by archived status) |
| `solidtime_create_client` | Create a client |
| `solidtime_update_client` | Update a client's name |
| `solidtime_delete_client` | Permanently delete a client |

### Tags (4 tools)

| Tool | Description |
|------|-------------|
| `solidtime_list_tags` | List all tags |
| `solidtime_create_tag` | Create a tag |
| `solidtime_update_tag` | Update a tag's name |
| `solidtime_delete_tag` | Permanently delete a tag |

### Tasks (4 tools)

| Tool | Description |
|------|-------------|
| `solidtime_list_tasks` | List tasks (filter by project, done status) |
| `solidtime_create_task` | Create a task within a project |
| `solidtime_update_task` | Update task name, done status, or estimated time |
| `solidtime_delete_task` | Permanently delete a task |

### Members (5 tools)

| Tool | Description |
|------|-------------|
| `solidtime_list_members` | List all members with roles and billable rates |
| `solidtime_update_member` | Update a member's role or billable rate |
| `solidtime_remove_member` | Remove a member from the organization |
| `solidtime_invite_placeholder_member` | Invite a placeholder member to create an account |
| `solidtime_make_placeholder_member` | Convert a real member into a placeholder |

### Organizations (2 tools)

| Tool | Description |
|------|-------------|
| `solidtime_get_organization` | Get organization details (name, currency, billable rate) |
| `solidtime_update_organization` | Update organization name, currency, or billable rate |

### Project Members (4 tools)

| Tool | Description |
|------|-------------|
| `solidtime_list_project_members` | List all members assigned to a project |
| `solidtime_add_project_member` | Add a member to a project with optional billable rate |
| `solidtime_update_project_member` | Update a project member's billable rate |
| `solidtime_remove_project_member` | Remove a member from a project |

### Invitations (4 tools)

| Tool | Description |
|------|-------------|
| `solidtime_list_invitations` | List all pending invitations |
| `solidtime_create_invitation` | Invite a new user by email |
| `solidtime_resend_invitation` | Resend an invitation email |
| `solidtime_delete_invitation` | Delete a pending invitation |

### Users (1 tool)

| Tool | Description |
|------|-------------|
| `solidtime_get_current_user` | Get your user profile and resolved member ID |

## Usage Examples

**Start tracking time:**
> "Start a timer for the website redesign project"

**Log completed work:**
> "Create a time entry for today 9:00-11:30 on the API project, tagged as development"

**Get a weekly report:**
> "Show me a report of this week's hours grouped by project"

**Check what's running:**
> "Is there a timer running?"

**Manage team members:**
> "List all members in the organization"

**Invite someone:**
> "Invite alice@example.com to the organization as an employee"

## Troubleshooting

### "Authentication failed"
Your `x-solidtime-api-token` is invalid or expired. Generate a new one in SolidTime under Settings > API.

### "Permission denied"
Your token doesn't have access to the specified organization. Verify `x-solidtime-organization-id`.

### "Cannot reach SolidTime"
Check that `x-solidtime-api-url` is correct and the instance is accessible. For self-hosted: ensure the URL includes the protocol (e.g., `https://solidtime.example.com`).

### "Could not find member for user"
The authenticated user is not a member of the specified organization. Check `x-solidtime-organization-id`.

### "Session not found"
Sessions expire after 30 minutes of inactivity. Reconnect to create a new session.

## Development

```bash
git clone https://github.com/SwamiRama/solidtime-mcp-server.git
cd solidtime-mcp-server
npm install
npm run dev:http     # Run HTTP mode with tsx (dev)
npm run dev          # Run stdio mode with tsx (dev)
npm run build        # Compile TypeScript
npm run start:http   # Run compiled HTTP mode
npm run start        # Run compiled stdio mode
npm run lint         # ESLint
npm run format       # Prettier (write)
npm run format:check # Prettier (check only)
npm run typecheck    # Type checking
npm run inspector    # Test with MCP Inspector
```

## License

MIT