solidtime-mcp/README.md

solidtime-mcp-server

Cloud-hosted MCP server for SolidTime — 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:

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

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

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

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