goalslot-mcp
goalslot-mcp
GoalSlot 用の MCP サーバーです。これは、自分の GoalSlot アカウントに対して、目標、タスク、週間スケジュールテンプレート、時間追跡、共有タイマー、レポート、メモ、ジャーナルのツールを AI アシスタントに提供します。
stdio 上で動作するため、任意の MCP ホストが起動できます。ツールをうまく使う方法をモデルに教える4つのスキルが同梱されています。
インストール
このサーバーは CLI が書き込んだ資格情報を読み取るため、先に goalslot CLI にサインインしておく必要があります。このサーバー自体がログインフローを実行することはありません。
npm install -g goalslot-cli
goalslot login次に、MCP サーバーを Claude Code に追加します:
claude mcp add goalslot -- npx -y goalslot-mcpClaude Desktop や、JSON 設定を受け取る任意のホストの場合:
{
"mcpServers": {
"goalslot": {
"command": "npx",
"args": ["-y", "goalslot-mcp"]
}
}
}動作確認:
npx -y goalslot-mcp --list-toolsこのパッケージはまだ npm に公開されていません。公開されるまでは、ソースからインストールしてください: リポジトリをクローンし、
npm install && npm run buildを実行してから、ホストをnode /path/to/goalslot-mcp/dist/cli.jsに指定します。
Related MCP server: Chisel Planner
認証の仕組み
このサーバーにはログインフローはありません。stdio がプロトコルチャネルであるため、サーバーは何かをプロンプト表示できず、モデルにトークンを処理させるのはさらに悪いでしょう。マシン上に既に存在する資格情報を読み取ります。
解決順序:
環境変数
GOALSLOT_ACCESS_TOKEN(設定されていて空でない場合)$GOALSLOT_CONFIG_DIR/credentials.jsonWindows では
%APPDATA%\goalslot\credentials.json$XDG_CONFIG_HOME/goalslot/credentials.json、それ以外の場合は~/.config/goalslot/credentials.json
このファイルは goalslot login によって書き込まれ、CLI と共有されます。その形式は次のとおりです:
{
"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 と apiUrl は両方とも読み取られ、同じ値で書き込まれるため、CLI とこのサーバーが互いに上書きすることはありません。未知のキーは書き換え後も保持されます。
CLI トークンは、typ: "cli" と、失効可能なトークン行を指定する cid クレームを持つ通常の Bearer JWT であり、通常の API ルートはすべてこれを受け入れます。アクセストークンの有効期限は1時間です。401 が返された場合、このサーバーは POST /api/auth/cli/token/refresh に対してリフレッシュトークンをローテーションし、新しいペアを 使用する前に アトミックにディスクに書き込み、元のリクエストを1回再試行します。ローテーションはシングルフライトです: リフレッシュトークンは一度きりであり、ローテーション済みのトークンを再試行すると資格情報全体が失効するため、同時に2つのリフレッシュが発生すると恒久的なログアウトになります。
トークン、ヘッダー、Authorization 行がログに書き込まれることは、どのレベルでも一切ありません。
資格情報が存在しないか無効な場合、すべてのツールは構造化された NOT_AUTHENTICATED または SESSION_EXPIRED を返し、モデルに goalslot login を実行するよう指示します。トークンを貼り付けるよう求めることはありません。
ヘッドレスと CI
GOALSLOT_ACCESS_TOKEN はファイルを完全に上書きします。リフレッシュを機能させたい場合は GOALSLOT_REFRESH_TOKEN と組み合わせてください。これがない場合、リフレッシュは無効になり、1時間のアクセストークンが期限切れになるとセッションは終了します。長期間の使用には、代わりに GOALSLOT_CONFIG_DIR を設定し、サーバーにファイルを管理させてください。
ツール
読み取りツールが9つ、書き込みツールが9つあります。読み取りツールは自由に呼び出しても安全で、readOnlyHint と注釈されています。各書き込みツールの説明は WRITES. で始まり、ここで公開されているものでユーザーデータを削除するものはありません。
読み取り
ツール | 説明 |
| オリエンテーション用の呼び出しで、引数はありません。ユーザー、プラン制限と現在の使用状況、カテゴリの値文字列、ラベル、タイムゾーン、今日の日付、今週、および実行中のタイマーを返します。すべてのスキルが最初にこれを呼び出します。 |
| 目標時間、記録済み時間、進捗、期限、ラベルを含む目標。オプションでステータス、カテゴリ、ラベルのフィルターが可能です。 |
| 1つの目標を完全に取得します。オプションで、ユーザーが書いた振り返りも含みます。 |
| ステータス、目標、スケジュールブロック、または曜日でフィルタリングされたタスク。大きなバックログがコンテキストを圧迫しないように上限があります。 |
| 週間スケジュールテンプレート。日ごとにグループ化され、開始時刻でソートされ、1日あたりの予定分数が含まれます。 |
| 期間またはプリセットにわたる個々の時間エントリと合計。オプションの目標フィルターとテキスト検索があります。 |
| 1つの |
| タイトルまたは本文の部分文字列でメモを検索するか、IDで1件取得します。ツリーパスを返し、HTML本文をマークダウンに変換します。 |
| 日付でマージされたジャーナルエントリとデイリーチェックイン: 気分、エネルギー、集中度、うまくいったこと、妨げになったこと。 |
書き込み
ツール | 説明 |
| 目標を作成します。 |
| ステータスを含む目標を更新します。 |
| タスクを作成します。オプションで目標とスケジュールブロックにリンクできます。 |
|
|
| 既に費やした時間を記録します。 |
| 共有サーバータイマーを開始します。静かに引き継ぐのではなく、 |
| タイマーを停止して時間エントリにするか、破棄します。 |
| 週間テンプレート内の1つのブロックを作成、更新、または削除します。 |
| 1つの日付のジャーナルエントリとデイリーチェックインをアップサートします。マークダウン入力、TipTap HTML 出力。 |
意図的にツールにしないもの
目標、タスク、時間エントリの削除、スケジュール全体のクリア、公開または他の人との共有、AI コーチのチャットエンドポイント、請求とアカウント設定、テンプレートのインポート。連鎖的な影響を伴う破壊や個人データを公開するものは、エージェントがループで呼び出せる場所ではなく、人間が入力する場所に属します。GoalSlot アプリまたは CLI を使用してください。
ツールが強制する規約
期間は整数分 で、常に
durationMinutesという名前で、裸のdurationではありません。読み取りでは表示専用にdurationHoursを浮動小数点数として返します。目標のtargetHoursは唯一の例外です。日付は
YYYY-MM-DDで、時刻が含まれる場合は境界で拒否されます。「今日」は UTC ISO スライスではなく、あなたのタイムゾーンで計算されます。スケジュールは繰り返しの週間テンプレート であり、日付付きのイベントではありません。関連するすべてのツールの説明にその旨が記載されています。
dayOfWeekは日曜日始まり(0 = 日曜日)で、週次レポートが使用する月曜日始まりの順序とは異なります。両方ともインラインでラベル付けされ、すべてのレスポンスにはdayNameが含まれます。週次バケットは、API サーバーのタイムゾーンで導出され、1日ずれる可能性がある API の保存済み
dayOfWeek列から読み取るのではなく、エントリの日付から再計算されます。
エラー
失敗は isError: true と1つの JSON オブジェクトとして返されます:
{
"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 はモデル向けに命令形で書かれています。コード: 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。
スキル
4つのスキルが skills/ に同梱されています。これらはツールの説明では表現できない判断を担います: 呼び出しの順序、書き込み前に確認すべきこと、言うべきでないこと。
スキル | 使用時 |
| 週の計画、目標のための時間のブロック、スケジュールの再調整。 |
| 未追跡の時間のキャッチアップ、エントリの修正、タイマーの操作。 |
| 週の終わり、「今週はどうだったか」、振り返りの作成。 |
| 「X に対して順調か」、目標の削減と期限の延期の判断。 |
スキルフォルダにディレクトリをコピーして Claude Code にインストールします:
# 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クローンからは、代わりにリポジトリの skills/* をコピーしてください。プロジェクトスコープでも機能します: リポジトリ内の .claude/skills/ に配置します。
設定
変数 | 効果 |
|
|
| 資格情報ファイルを完全に上書きします。CI の脱出ハッチ。 |
| 上記と組み合わせるリフレッシュトークン。ローテーションはメモリ内のみで保持されます。 |
| API ベース URL。デフォルトは |
| ログイン時のタイムゾーンを上書きする IANA タイムゾーン。 |
| すべての書き込みツールが |
| プロセスごとに許可される書き込み呼び出し数。デフォルトは25。暴走ループは、無料アカウントのみをバックストップするプラン制限ではなく、ここで停止します。 |
HTTP トランスポート
オプションで、フラグの後ろにあります:
npx -y goalslot-mcp --http --port 7801同じツールレジストリを http://127.0.0.1:7801/mcp でストリーミング可能な HTTP トランスポート経由でステートレスに提供します。
これはシングルユーザーかつローカルのみです。すべてのリクエストはこのマシンのGoalSlot認証情報で処理されます。呼び出し元ごとの認証、OAuth、トークンの管理は一切ないため、ポートに到達できる人は誰でもアカウントを読み書きできます。ループバックにバインドされており、そのままにしておく必要があります。goal-slot-api#55で追跡されているホスト型マルチテナントMCPサーバーではありません。それには本格的なOAuthフローとユーザーごとのトークン保存が必要であり、それは別の作業です。
stdioがサポートされているパスです。
開発
npm install
npm run typecheck
npm test
npm run build
node dist/cli.js --list-toolsTypeScript strict、ESM、Node 20以降。テストはスタブ化されたfetchを使用したvitestです。スイート内の何もライブAPIに触れません。CIはUbuntuとWindowsでNode 20と22に対して型チェック、テスト、ビルドを実行します。
ライセンス
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.
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-