Skip to main content
Glama

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: Chisel Planner

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

Tool

What it does

goalslot_get_context

Orientation call, no arguments. User, plan limits and current usage, category value strings, labels, timezone, today's date, the current week, and any running timer. Every skill calls this first.

goalslot_list_goals

Goals with target hours, logged hours, progress, deadline and labels. Optional status, category and label filters.

goalslot_get_goal

One goal in full, optionally with the user's written reflections on it.

goalslot_list_tasks

Tasks filtered by status, goal, schedule block or day of week, capped so a big backlog cannot flood the context.

goalslot_get_schedule

The weekly schedule template, grouped by day and sorted by start time, with planned minutes per day.

goalslot_list_time_entries

Individual time entries over a window or a preset, with a total. Optional goal filter and text search.

goalslot_get_report

Nine report endpoints behind one view enum: dashboard, weekly, monthly, detailed, summary, day_by_task, day_total, schedule, goals_progress.

goalslot_search_notes

Finds notes by title or body substring, or fetches one by id. Returns the tree path and converts the HTML body to markdown.

goalslot_get_journal

Journal entries and daily check-ins merged by date: mood, energy, focus, what worked, what blocked.

Write

Tool

What it does

goalslot_create_goal

Creates a goal. targetHours is the one field measured in hours.

goalslot_update_goal

Updates a goal including its status. Deliberately cannot set loggedHours.

goalslot_create_task

Creates a task, optionally linked to a goal and a schedule block.

goalslot_update_task

The whole task lifecycle behind an action: update, complete (which also logs time), restore.

goalslot_log_time

Records time already spent. Supports dryRun. Credits the linked goal.

goalslot_start_timer

Starts the shared server timer. Returns TIMER_ALREADY_RUNNING rather than silently taking over.

goalslot_stop_timer

Stops the timer into a time entry, or discards it.

goalslot_manage_schedule_block

Creates, updates or deletes one block in the weekly template. Supports dryRun and updateScope.

goalslot_write_journal

Upserts a journal entry and a daily check-in for one date. Markdown in, TipTap HTML out.

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.

Skill

When

goalslot-plan-my-week

Planning a week, blocking time for a goal, rebalancing the schedule.

goalslot-log-time

Catching up on untracked time, correcting entries, driving the timer.

goalslot-weekly-review

End of week, "how did my week go", writing a reflection.

goalslot-goal-checkup

"Am I on track for X", deciding between cutting a target and moving a deadline.

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

Variable

Effect

GOALSLOT_CONFIG_DIR

Directory holding credentials.json. Checked first.

GOALSLOT_ACCESS_TOKEN

Overrides the credential file entirely. CI escape hatch.

GOALSLOT_REFRESH_TOKEN

Refresh token to pair with the above. Rotations are held in memory only.

GOALSLOT_API_URL

API base URL. Defaults to https://api.goalslot.io/api.

GOALSLOT_TZ

IANA timezone overriding the one from login.

GOALSLOT_MCP_READONLY=1

Every write tool returns READ_ONLY_MODE. Set this when pointing an agent you do not fully trust at a live account.

GOALSLOT_MCP_MAX_WRITES

Write calls allowed per process. Defaults to 25. A runaway loop stops here rather than at the plan limit, which only backstops free accounts.

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

Available Tools

18 tools
goalslot_create_goalCreate a goalA

WRITES. Creates a new goal on the user's account. category must be a value string from get_context.categories[].value, not a display name. targetHours is the one field measured in HOURS; everything else in this server is minutes. Creating a goal counts against the plan limit reported by get_context. If the account is at its limit this returns PLAN_LIMIT, so check the limit before calling rather than after. Confirm the title, category and target with the user before calling. Do not invent goals from an offhand remark.

Inputs: title (required), category (required), targetHours (required), color, +3 more.

goalslot_create_taskCreate a taskA

WRITES. Creates a task, optionally attached to a goal and to a weekly schedule block. estimatedMinutes is in MINUTES. Creating a task does not log any time; completing it with update_task does. Prefer attaching a goalId when the task clearly serves one, because that is what makes reports and goal progress meaningful later.

Inputs: title (required), notes, goalId, status, +5 more.

goalslot_get_contextGet GoalSlot account contextA
Read-only

READ ONLY. Call this first, before any other GoalSlot tool, in every session. It returns the facts the other tools require and that you must not guess: the signed-in user, the plan limits and how much of each is already used, the category VALUE strings that create_goal and manage_schedule_block require, the labels, the timezone, today's date in that timezone, the current Monday-first week window, and any timer already running. Do not assume today's date from your own sense of time, and do not invent a category value. Both come from here. Cheap and side-effect free. Call it again after a long conversation rather than relying on a stale copy.

Inputs: no named parameters.

goalslot_get_goalGet one goalA
Read-only

READ ONLY. Full detail for a single goal, optionally with the user's own written reflections on it. Use this when the conversation is about one specific goal. For "how are all my goals doing", call list_goals instead, which is one request rather than many.

Inputs: goalId (required), includeReflections.

goalslot_get_journalGet journal entries and check-insA
Read-only

READ ONLY. Returns the user's written journal and their daily check-ins over a window, merged by date. A journal entry is free-written prose plus optional mood and energy. A check-in is the structured version: mood, energy and focus each 1 to 5, plus short "what worked" and "what blocked me" notes. This is what answers "how did my week feel", as opposed to get_report which answers "where did my hours go". Read both when the user asks how a week went. Journal bodies are stored as HTML and converted to markdown here. Quote the user's own words rather than paraphrasing them.

Inputs: date, preset, endDate, include, +1 more.

goalslot_get_reportGet a time reportA
Read-only

READ ONLY. The single reporting tool. Pick a view; the tool routes to the right report and normalizes the answer. Views: "day_total" is minutes per day, the best default for "how did my week go". "summary" with groupBy goal or category is the per-goal rollup. "detailed" lists every entry grouped by day. "day_by_task" is per day broken down by task. "schedule" compares hours PLANNED in the weekly template against hours actually LOGGED, which is the only way to tell "I never allocated time" apart from "I allocated it and did not honour it". "goals_progress" and "dashboard" are account-wide snapshots that ignore the date range. "weekly" and "monthly" are convenience windows. The response always echoes the resolved date range. Quote that range to the user rather than saying "this week", and never state a number that did not come back from a tool. All durations are minutes. Percentages are already computed; do not recompute them.

Inputs: view (required), preset, endDate, goalIds, +6 more.

goalslot_get_scheduleGet the weekly scheduleA
Read-only

READ ONLY. Returns the user's weekly schedule template, grouped by day and sorted by start time. The GoalSlot schedule is a REPEATING WEEKLY TEMPLATE, not a calendar of dated events. A block on Tuesday 09:00-12:00 happens every Tuesday. There is no way to schedule something for one specific date. Times are wall-clock HH:mm with no date and no timezone. dayOfWeek is Sunday-first: 0 = Sunday through 6 = Saturday. Call this before proposing any new block, so you can see which windows are already taken.

Inputs: dayOfWeek.

goalslot_list_goalsList goalsA
Read-only

READ ONLY. Lists the user's goals with target hours, hours already logged, progress and deadline. This is the tool that answers "what am I working on" and "am I behind". loggedHours is accumulated by time entries, so it moves whenever log_time is called with a goalId. Returns ids you must reuse verbatim when calling create_task, log_time or manage_schedule_block.

Inputs: status, labelIds, categories, includeStats.

goalslot_list_tasksList tasksA
Read-only

READ ONLY. Lists tasks, optionally filtered by status, goal, schedule block or day of week. Statuses are BACKLOG, TODO, DOING, DONE. Results are capped by limit (default 50) so a large backlog cannot flood the conversation; the response says whether it was truncated. dayOfWeek here is Sunday-first (0 = Sunday), which is not the Monday-first ordering that weekly reports use.

Inputs: limit, goalId, status, statuses, +2 more.

goalslot_list_time_entriesList time entriesA
Read-only

READ ONLY. Returns the individual time entries the user logged over a window, with a total. This is the raw record of what was tracked. For aggregates, comparisons and per-goal rollups use get_report instead, which is one call rather than summing these yourself. Every duration is returned as durationMinutes (whole minutes, authoritative) and durationHours (a float for display only, never send it back). The response always echoes the resolved date range, so check it matches what the user meant before quoting numbers.

Inputs: limit, goalId, preset, search, +2 more.

goalslot_log_timeLog a time entryA

WRITES. Records time the user already spent. This is the workhorse tool for catching up on untracked work. durationMinutes is in whole MINUTES: an hour and a half is 90. date is a calendar date in the user's timezone, taken from get_context.today, never guessed. When goalId is set this ALSO increases that goal's logged hours. That is usually what the user wants, but it means a wrong goalId quietly corrupts goal progress, so confirm the goal before logging. Never invent a duration. If the user did not say how long something took, ask. Restate the minutes back in hours when you confirm, so a units mistake is visible. Entries count against the per-day task limit on free plans. Use dryRun true to show a batch to the user before committing it.

Inputs: date (required), taskName (required), durationMinutes (required), notes, +5 more.

goalslot_manage_schedule_blockCreate, update or delete a schedule blockA

WRITES. Creates, updates or deletes one block in the weekly schedule template. The GoalSlot schedule is a REPEATING WEEKLY TEMPLATE, not a calendar of dated events. A block on Tuesday 09:00-12:00 happens every Tuesday. There is no way to schedule something for one specific date. Adding a block therefore changes every future week, not one date. Say that back to the user before you commit a plan. Overlapping an existing block is rejected with SCHEDULE_CONFLICT. On a conflict, re-read that day with get_schedule and shift your proposal. Never delete the incumbent block to make room without asking. Use dryRun true to validate a whole proposed week and show it to the user before writing anything. Blocks count against the plan limit in get_context, so stop one short of it rather than erroring into it. action "delete" removes a single block. There is no way to clear the whole schedule from this server, deliberately.

Inputs: action (required), color, title, dryRun, +8 more.

goalslot_search_notesSearch notesA
Read-only

READ ONLY. Finds notes by a substring of their title or body, or fetches one note by id. Notes are a tree, so every result carries its full path such as "Work / Meetings / Standup". Bodies are stored as HTML and are converted to markdown here, then truncated to maxChars, so long notes come back readable rather than as a wall of tags. With no query this lists the user's notes without their bodies, which is the cheap way to see what exists before pulling one. This server cannot create, edit, delete or share notes. Say so rather than looking for another tool.

Inputs: limit, query, noteId, maxChars, +1 more.

goalslot_start_timerStart the timerA

WRITES. Starts the shared GoalSlot timer for this account. The same timer the user sees in the web and mobile apps, not a private one. Only one timer can run at a time. If one is already running this returns TIMER_ALREADY_RUNNING with what it is tracking and how long it has been going. Do not pass takeOver to get past that on your own: takeOver DISCARDS the running session and its elapsed time is lost with no time entry written. Show the user what is running and let them choose to stop it or replace it. Attach goalId when the work belongs to a goal, so stopping the timer credits that goal.

Inputs: notes, goalId, taskId, takeOver, +2 more.

goalslot_stop_timerStop or discard the timerA

WRITES. Stops the running timer and converts it into a time entry, or discards it. Stopping is atomic and credits the linked goal, so the goal's logged hours go up by the elapsed minutes. Duration is floored at 1 minute and capped at 12 hours: a session left open overnight writes 12 hours, not the real elapsed time, and the response says so via "capped". discard true writes nothing at all and the elapsed time is lost. Only use it when the user says the timer was started by mistake. Attribution fields sent here override whatever the timer was started with.

Inputs: notes, goalId, taskId, discard, +2 more.

goalslot_update_goalUpdate a goalA
Idempotent

WRITES. Updates fields on an existing goal, including its status. There is deliberately no way to set loggedHours here. Logged hours are accumulated from time entries; to change them, add or correct a time entry with log_time. There is no archived status. PAUSED is how the user shelves a goal without deleting it. Deleting a goal is not available as a tool at all; tell the user to run the CLI if they want one gone. Only send the fields that should change.

Inputs: goalId (required), color, title, status, +4 more.

goalslot_update_taskUpdate, complete or restore a taskA
Idempotent

WRITES. One tool for the whole task lifecycle, selected by action. action "update" edits fields. action "complete" marks the task done AND creates a time entry for actualMinutes, which also increases the linked goal's logged hours; it counts against the per-day task limit. action "restore" reopens a completed task. actualMinutes is required for complete and is in whole MINUTES. Never guess it: ask the user how long the task actually took.

Inputs: action (required), taskId (required), date, notes, +9 more.

goalslot_write_journalWrite a journal entry or check-inA
Idempotent

WRITES. Saves the user's journal entry and daily check-in for one date. Both are upserts keyed by date. IMPORTANT: mode "replace" (the default) REPLACES that day's whole journal body. Use mode "append" to add to what is already there. If the day may already have content and the user did not ask you to overwrite it, append. content is markdown and is converted to the HTML the GoalSlot editor stores. Write in the user's voice, using their words, not a summary of them. focus, worked and blocked are part of the check-in, and the check-in requires mood, energy and focus together. Supplying only some of the three is rejected rather than guessed at. Never invent a mood, an energy level or a reflection the user did not express.

Inputs: date (required), mode, mood, focus, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 18 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action (e.g., log_time vs. stop_timer, get_report vs. list_time_entries, get_schedule vs. manage_schedule_block). The overlapping cases are clearly differentiated by descriptions, such as manual logging vs. timer-driven logging, and raw entries vs. aggregated reports. No two tools appear to do the same thing.

    Naming Consistency5/5

    All tools follow the 'goalslot_' prefix plus a consistent snake_case verb_noun pattern (e.g., get_goal, create_task, stop_timer). The verb choice is uniform across read (get/list/search) and write (create/update/start/stop/manage/log/write) operations. There are no stylistic deviations or mixed conventions.

    Tool Count4/5

    18 tools cover a broad domain (goals, tasks, schedule, time tracking, reporting, journal, timer, notes). While this falls slightly above the typical 3–15 'well-scoped' range, the count is justified by the variety of features; each tool has a clear purpose and none are redundant. It feels comprehensive without being bloated.

    Completeness3/5

    The core workflows are covered: goal lifecycle (create/update, though delete is deliberately absent), task lifecycle (create/update/complete/restore, but no delete), schedule management (create/update/delete), time logging (manual and timer), reporting (multiple views), and journaling. However, there are no tools to delete or edit time entries, and goals/tasks cannot be fully removed, which are notable gaps for a productivity domain. The server explicitly documents these limitations, but they still create dead ends for agents.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables authenticated MCP clients to manage projects, tasks, habits, and daily capacity through tool calls.
      8 npm
      ISC
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to connect to the OnTime personal workbench via MCP to manage tasks, projects, and goals through natural language, including creating sprint projects, logging progress, and querying workbench state in real time.
      1
      -