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 and docker-compose included
• 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 Compose (recommended)

docker compose up -d

Docker Manual

docker build -t solidtime-mcp-server .
docker run -p 3000:3000 solidtime-mcp-server

Server Environment Variables

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

Variable	Required	Default	Description
PORT	No	3000	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