Skip to main content
Glama

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-mcp

Claude 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 がプロトコルチャネルであるため、サーバーは何かをプロンプト表示できず、モデルにトークンを処理させるのはさらに悪いでしょう。マシン上に既に存在する資格情報を読み取ります。

解決順序:

  1. 環境変数 GOALSLOT_ACCESS_TOKEN(設定されていて空でない場合)

  2. $GOALSLOT_CONFIG_DIR/credentials.json

  3. Windows では %APPDATA%\goalslot\credentials.json

  4. $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. で始まり、ここで公開されているものでユーザーデータを削除するものはありません。

読み取り

ツール

説明

goalslot_get_context

オリエンテーション用の呼び出しで、引数はありません。ユーザー、プラン制限と現在の使用状況、カテゴリの値文字列、ラベル、タイムゾーン、今日の日付、今週、および実行中のタイマーを返します。すべてのスキルが最初にこれを呼び出します。

goalslot_list_goals

目標時間、記録済み時間、進捗、期限、ラベルを含む目標。オプションでステータス、カテゴリ、ラベルのフィルターが可能です。

goalslot_get_goal

1つの目標を完全に取得します。オプションで、ユーザーが書いた振り返りも含みます。

goalslot_list_tasks

ステータス、目標、スケジュールブロック、または曜日でフィルタリングされたタスク。大きなバックログがコンテキストを圧迫しないように上限があります。

goalslot_get_schedule

週間スケジュールテンプレート。日ごとにグループ化され、開始時刻でソートされ、1日あたりの予定分数が含まれます。

goalslot_list_time_entries

期間またはプリセットにわたる個々の時間エントリと合計。オプションの目標フィルターとテキスト検索があります。

goalslot_get_report

1つの view 列挙型の背後にある9つのレポートエンドポイント: dashboard、weekly、monthly、detailed、summary、day_by_task、day_total、schedule、goals_progress。

goalslot_search_notes

タイトルまたは本文の部分文字列でメモを検索するか、IDで1件取得します。ツリーパスを返し、HTML本文をマークダウンに変換します。

goalslot_get_journal

日付でマージされたジャーナルエントリとデイリーチェックイン: 気分、エネルギー、集中度、うまくいったこと、妨げになったこと。

書き込み

ツール

説明

goalslot_create_goal

目標を作成します。targetHours は時間で測定される唯一のフィールドです。

goalslot_update_goal

ステータスを含む目標を更新します。loggedHours は意図的に設定できません。

goalslot_create_task

タスクを作成します。オプションで目標とスケジュールブロックにリンクできます。

goalslot_update_task

action によるタスクライフサイクル全体: update、complete(時間も記録)、restore。

goalslot_log_time

既に費やした時間を記録します。dryRun をサポートします。リンクされた目標にクレジットされます。

goalslot_start_timer

共有サーバータイマーを開始します。静かに引き継ぐのではなく、TIMER_ALREADY_RUNNING を返します。

goalslot_stop_timer

タイマーを停止して時間エントリにするか、破棄します。

goalslot_manage_schedule_block

週間テンプレート内の1つのブロックを作成、更新、または削除します。dryRun と updateScope をサポートします。

goalslot_write_journal

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/ に同梱されています。これらはツールの説明では表現できない判断を担います: 呼び出しの順序、書き込み前に確認すべきこと、言うべきでないこと。

スキル

使用時

goalslot-plan-my-week

週の計画、目標のための時間のブロック、スケジュールの再調整。

goalslot-log-time

未追跡の時間のキャッチアップ、エントリの修正、タイマーの操作。

goalslot-weekly-review

週の終わり、「今週はどうだったか」、振り返りの作成。

goalslot-goal-checkup

「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/ に配置します。

設定

変数

効果

GOALSLOT_CONFIG_DIR

credentials.json を保持するディレクトリ。最初にチェックされます。

GOALSLOT_ACCESS_TOKEN

資格情報ファイルを完全に上書きします。CI の脱出ハッチ。

GOALSLOT_REFRESH_TOKEN

上記と組み合わせるリフレッシュトークン。ローテーションはメモリ内のみで保持されます。

GOALSLOT_API_URL

API ベース URL。デフォルトは https://api.goalslot.io/api。

GOALSLOT_TZ

ログイン時のタイムゾーンを上書きする IANA タイムゾーン。

GOALSLOT_MCP_READONLY=1

すべての書き込みツールが READ_ONLY_MODE を返します。完全に信頼していないエージェントをライブアカウントに向ける場合に設定します。

GOALSLOT_MCP_MAX_WRITES

プロセスごとに許可される書き込み呼び出し数。デフォルトは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-tools

TypeScript strict、ESM、Node 20以降。テストはスタブ化されたfetchを使用したvitestです。スイート内の何もライブAPIに触れません。CIはUbuntuとWindowsでNode 20と22に対して型チェック、テスト、ビルドを実行します。

ライセンス

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.

    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
      -