solidtime-mcp (Solidtime MCP connector)

MCP connector for a Solidtime instance. It speaks public REST API v1 over stdio and over stateless Streamable HTTP on localhost.

Solidtime is AGPL-3.0 software. Self-host it, or point this connector at your own cloud account. This connector does not grant any right to the Solidtime name, and it does not imply endorsement.

This connector is MIT. It is a BYO-token client. It only calls the public REST API. It is not affiliated with solidtime-io.

The connector covers all 81 operations in solidtime.openapi.json plus the extra client routes in solidtime.client-routes.ts.txt (99 operations, 53 tools). Week copy and timesheet bulk entry are not on the public REST API, so they are not tools. Project and task estimates use estimated_time in seconds.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication. Keep it on localhost.

Create a personal API token in Solidtime under Profile settings, Create API Token. The connector sends it as Authorization: Bearer <token> and never prints it.

{
  "mcpServers": {
    "solidtime": {
      "command": "node",
      "args": ["/workspace/connectors/solidtime/dist/index.js"],
      "env": {
        "SOLIDTIME_URL": "http://127.0.0.1:8088",
        "SOLIDTIME_API_TOKEN": "...",
        "SOLIDTIME_ORGANIZATION_ID": "...",
        "SOLIDTIME_ALLOW_WRITES": "false",
        "SOLIDTIME_CONTACT": "you@example.com"
      }
    }
  }
}

Cloud accounts use https://app.solidtime.io as SOLIDTIME_URL. A trailing /api is stripped.

Docker (HTTP, no authentication, localhost only):

docker build -t solidtime-mcp .
docker run -p 3000:3000 \
  -e SOLIDTIME_URL=http://host.docker.internal:8088 \
  -e SOLIDTIME_API_TOKEN=... \
  solidtime-mcp

Do not put the API token in the image.

Related MCP server: solidtime-mcp-server

Tools

member_id is the membership id from solidtime_memberships, not the user id.

billable_rate is cents per hour. Changing it can reprice existing time entries.

When no timer is running, solidtime_timer_active returns { data: null, active: false }.

Professional invoice routes that are missing on the instance return a not-available error.

Environment

Invalid values are reported by field name and issue code. The rejected value is not included.

Safety

A write tool returns a dry-run preview when confirm is omitted. The preview is the method, path, query, and body that would be sent. Secrets are redacted.

confirm must be the boolean true. false and the string "true" are rejected.

When confirm is true and SOLIDTIME_ALLOW_WRITES is not true, the tool still returns the preview, sets blocked to true, and does not call the instance.

Writes include POST, PUT, PATCH, DELETE, timer start and stop, bulk time-entry update and delete, invites, rate changes, import, export, and trial cancel.

Rate-change previews warn that existing time entries can be repriced. Delete and bulk previews warn that the action is irreversible.

The API token is removed from tool results, error text, and logs, including its URL-encoded form. It is refused in the query string, the base URL, the User-Agent, and a JSON request body. access_token, password, and Authorization values are redacted. Absolute server filesystem paths are dropped.

HTTP 401 is [upstream] authentication failed. HTTP 402 is [upstream] with a quota or payment note. HTTP 403 for a missing Professional feature is [upstream] not available on this plan or instance. HTTP 404 is [not-found]. HTTP 422 surfaces validation messages. HTTP 429 is [rate-limit] with Retry-After and the 200/min cap.

HTTP mode has no authentication. Do not expose it beyond localhost.

Licence

Solidtime is AGPL-3.0 (https://github.com/solidtime-io/solidtime). This connector is MIT. It only calls the public REST API. Bring your own token. Not affiliated with solidtime-io.

License

MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Solidtime project or its owners.

The upstream solidtime.openapi.json comes from a AGPL-3.0 project, so it is not shipped here. src/operations.ts was generated from it, and tests fall back to a route-only fixture in test/fixtures/. To regenerate, download the spec from the upstream project into the repo root (it is gitignored) and run node scripts/gen-operations.mjs.