goalslot-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@goalslot-mcp Show me my today's tasks and time logged"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 loginThen add the MCP server to Claude Code:
claude mcp add goalslot -- npx -y goalslot-mcpFor 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-toolsThis 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 atnode /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:
GOALSLOT_ACCESS_TOKENfrom the environment, if set and non-empty.$GOALSLOT_CONFIG_DIR/credentials.json.%APPDATA%\goalslot\credentials.jsonon Windows.$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 |
| 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. |
| Goals with target hours, logged hours, progress, deadline and labels. Optional status, category and label filters. |
| One goal in full, optionally with the user's written reflections on it. |
| Tasks filtered by status, goal, schedule block or day of week, capped so a big backlog cannot flood the context. |
| The weekly schedule template, grouped by day and sorted by start time, with planned minutes per day. |
| Individual time entries over a window or a preset, with a total. Optional goal filter and text search. |
| Nine report endpoints behind one |
| Finds notes by title or body substring, or fetches one by id. Returns the tree path and converts the HTML body to markdown. |
| Journal entries and daily check-ins merged by date: mood, energy, focus, what worked, what blocked. |
Write
Tool | What it does |
| Creates a goal. |
| Updates a goal including its status. Deliberately cannot set |
| Creates a task, optionally linked to a goal and a schedule block. |
| The whole task lifecycle behind an |
| Records time already spent. Supports |
| Starts the shared server timer. Returns |
| Stops the timer into a time entry, or discards it. |
| Creates, updates or deletes one block in the weekly template. Supports |
| 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 bareduration. Reads also returndurationHoursas a float for display only. A goal'stargetHoursis the single exception.Dates are
YYYY-MM-DDand 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.
dayOfWeekis Sunday-first (0 = Sunday), which is not the Monday-first ordering weekly reports use. Both are labelled inline and every response carries adayName.Weekly buckets are recomputed from entry dates rather than read from the API's stored
dayOfWeekcolumn, 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 |
| Planning a week, blocking time for a goal, rebalancing the schedule. |
| Catching up on untracked time, correcting entries, driving the timer. |
| End of week, "how did my week go", writing a reflection. |
| "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\" -RecurseFrom a clone, copy skills/* from the repo instead. Project-scoped works too: put them in .claude/skills/ inside a repo.
Configuration
Variable | Effect |
| Directory holding |
| Overrides the credential file entirely. CI escape hatch. |
| Refresh token to pair with the above. Rotations are held in memory only. |
| API base URL. Defaults to |
| IANA timezone overriding the one from login. |
| Every write tool returns |
| 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 7801It 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-toolsTypeScript 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 toolsgoalslot_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 contextARead-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 goalARead-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-insARead-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 reportARead-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 scheduleARead-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 goalsARead-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 tasksARead-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 entriesARead-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 notesARead-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 goalAIdempotent
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 taskAIdempotent
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-inAIdempotent
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
Scored across 18 tools
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.
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.
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.
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
Related MCP Connectors
Your planner in every AI chat: tasks, calendar, docs, habits, goals and memory, over MCP.
Official Akiflow MCP for tasks, calendars, scheduling, time slots, and meeting transcripts.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to interact with ExecuFunction's project management, knowledge base, code indexing, and calendar tools via MCP, allowing natural language management of tasks, notes, and code.MIT
- AlicenseNot gradedqualityDmaintenanceEnables authenticated MCP clients to manage projects, tasks, habits, and daily capacity through tool calls.8 npmISC
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to create, read, and manage tasks and projects in a personal todo system through MCP tools.1MIT
- FlicenseNot gradedqualityCmaintenanceEnables 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-