goalslot-mcp

An MCP server for GoalSlot. It gives an AI assistant tools for goals, tasks, the weekly schedule template, time tracking, the shared timer, reports, notes and the journal, against your own GoalSlot account.

Runs over stdio, so any MCP host can spawn it. Ships four skills that teach a model how to use the tools well.

Install

You need the goalslot CLI signed in first, because this server reads the credential the CLI writes. It never runs a login flow itself.

npm install -g goalslot-cli
goalslot login

Then add the MCP server to Claude Code:

claude mcp add goalslot -- npx -y goalslot-mcp

For Claude Desktop, or any host that takes a JSON config:

{
  "mcpServers": {
    "goalslot": {
      "command": "npx",
      "args": ["-y", "goalslot-mcp"]
    }
  }
}

Check it is working:

npx -y goalslot-mcp --list-tools

This package is not published to npm yet. Until it is, install it from source: clone the repo, npm install && npm run build, then point the host at node /path/to/goalslot-mcp/dist/cli.js.

Related MCP server: GoHighLevel MCP Server

How auth works

There is no login flow in this server. stdio is the protocol channel, so a server cannot prompt for anything, and asking a model to handle a token would be worse. It reads a credential that already exists on the machine.

Resolution order:

1. GOALSLOT_ACCESS_TOKEN from the environment, if set and non-empty.

2. $GOALSLOT_CONFIG_DIR/credentials.json.

3. %APPDATA%\goalslot\credentials.json on Windows.

4. $XDG_CONFIG_HOME/goalslot/credentials.json, else ~/.config/goalslot/credentials.json.

The file is written by goalslot login and shared with the CLI. Its shape:

{
  "version": 1,
  "apiBaseUrl": "https://api.goalslot.io/api",
  "apiUrl": "https://api.goalslot.io/api",
  "accessToken": "<jwt>",
  "refreshToken": "gsl_rt_...",
  "accessTokenExpiresAt": "2026-08-25T12:00:00.000Z",
  "refreshTokenExpiresAt": "2026-11-23T00:00:00.000Z",
  "tokenId": "<uuid>",
  "scopes": ["full"],
  "user": { "id": "...", "email": "..." },
  "defaultTimezone": "Asia/Karachi",
  "weekStartsOn": 1
}

apiBaseUrl and apiUrl are both read and both written with the same value, so the CLI and this server cannot clobber each other. Unknown keys survive a rewrite.

CLI tokens are ordinary Bearer JWTs carrying typ: "cli" and a cid claim naming the revocable token row, and every normal API route accepts them. Access tokens live one hour. On a 401 this server rotates the refresh token against POST /api/auth/cli/token/refresh, writes the new pair to disk atomically before using it, and replays the original request once. Rotation is single-flight: refresh tokens are single use, and replaying a rotated one revokes the whole credential, so two concurrent refreshes would be a permanent logout.

No token, header or Authorization line is ever written to any log, at any level.

If the credential is missing or dead, every tool returns a structured NOT_AUTHENTICATED or SESSION_EXPIRED telling the model to have you run goalslot login. It will not ask you to paste a token.

Headless and CI

GOALSLOT_ACCESS_TOKEN overrides the file entirely. Pair it with GOALSLOT_REFRESH_TOKEN if you want refresh to work; without one, refresh is disabled and the session dies when the one-hour access token expires. For anything long-lived, set GOALSLOT_CONFIG_DIR instead and let the server manage the file.

Tools

Nine read tools and nine write tools. Read tools are safe to call freely and are annotated readOnlyHint. Every write tool's description starts with WRITES. and nothing exposed here deletes user data.

Read

Write

Deliberately not tools

Deleting goals, tasks and time entries; clearing the whole schedule; sharing anything publicly or with another person; the AI coach chat endpoints; billing and account settings; template imports. Destruction with cascading effects and anything that publishes personal data belongs where a human types it, not where an agent can call it in a loop. Use the GoalSlot app or the CLI.

Conventions the tools enforce

• Durations are whole minutes, always named durationMinutes, never a bare duration. Reads also return durationHours as a float for display only. A goal's targetHours is the single exception.

• Dates are YYYY-MM-DD and are rejected at the boundary if they carry a time. "Today" is computed in your timezone, not from a UTC ISO slice.

• The schedule is a repeating weekly template, not dated events. Every relevant tool description says so.

• dayOfWeek is Sunday-first (0 = Sunday), which is not the Monday-first ordering weekly reports use. Both are labelled inline and every response carries a dayName.

• Weekly buckets are recomputed from entry dates rather than read from the API's stored dayOfWeek column, which is derived in the API server's timezone and can be off by one.

Errors

Failures come back as isError: true with one JSON object:

{
  "error": {
    "code": "PLAN_LIMIT",
    "message": "You've reached your FREE plan limit for goals.",
    "httpStatus": 403,
    "retryable": false,
    "remedy": "The account is at its goal limit. Ask the user to pause a goal with update_goal (status PAUSED), delete one from the CLI, or upgrade. Do not retry.",
    "details": { "plan": "FREE", "limitType": "goals" }
  }
}

remedy is written in the imperative, for the model. Codes: NOT_AUTHENTICATED, SESSION_EXPIRED, PLAN_LIMIT, FORBIDDEN, SCHEDULE_CONFLICT, INVALID_INPUT, NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, WRITE_BUDGET_EXCEEDED, READ_ONLY_MODE, TIMER_ALREADY_RUNNING, NO_TIMER_RUNNING.

Skills

Four skills ship in skills/. They carry the judgement the tool descriptions cannot: which order to call things in, what to confirm before writing, and what not to say.

Install them into Claude Code by copying the directories into your skills folder:

# macOS and Linux
cp -r "$(npm root -g)/goalslot-mcp/skills/"* ~/.claude/skills/

# Windows PowerShell
Copy-Item "$(npm root -g)\goalslot-mcp\skills\*" "$env:USERPROFILE\.claude\skills\" -Recurse

From a clone, copy skills/* from the repo instead. Project-scoped works too: put them in .claude/skills/ inside a repo.

Configuration

HTTP transport

Optional, behind a flag:

npx -y goalslot-mcp --http --port 7801

It serves the same tool registry at http://127.0.0.1:7801/mcp over the streamable HTTP transport, statelessly.

This is single user and local only. Every request is served with this machine's GoalSlot credentials. There is no per-caller authentication, no OAuth and no token custody, so anyone who can reach the port can read and write the account. It binds to loopback and should stay there. It is not the hosted multi-tenant MCP server tracked in goal-slot-api#55; that needs a real OAuth flow and per-user token storage, which is a different piece of work.

stdio is the supported path.

Development

npm install
npm run typecheck
npm test
npm run build
node dist/cli.js --list-tools

TypeScript strict, ESM, Node 20 or newer. Tests are vitest with a stubbed fetch; nothing in the suite touches a live API. CI runs typecheck, tests and build on Node 20 and 22 across Ubuntu and Windows.

License

MIT