goalslot-mcp

一个用于 GoalSlot 的 MCP 服务器。它为 AI 助手提供针对目标、任务、每周日程模板、时间跟踪、共享计时器、报告、笔记和日志的工具，作用于你自己的 GoalSlot 账户。

它通过 stdio 运行，因此任何 MCP 主机都可以启动它。它附带四个技能，教模型如何很好地使用这些工具。

安装

你需要先登录 goalslot CLI，因为此服务器读取 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: GoHighLevel MCP Server

认证方式

此服务器中没有登录流程。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 令牌是普通的 Bearer JWT，带有 typ: "cli" 和命名可撤销令牌行的 cid 声明，所有常规 API 路由都接受它们。访问令牌有效期为 1 小时。在收到 401 时，此服务器会针对 POST /api/auth/cli/token/refresh 轮换刷新令牌，将新的一对原子地写入磁盘然后使用它，并重放原始请求一次。轮换是单飞的：刷新令牌是一次性的，重放已轮换的令牌会撤销整个凭据，因此两个并发刷新将导致永久注销。

任何令牌、标头或 Authorization 行都不会写入任何日志，无论级别如何。

如果凭据缺失或失效，每个工具都会返回结构化的 NOT_AUTHENTICATED 或 SESSION_EXPIRED，告诉模型让你运行 goalslot login。它不会要求你粘贴令牌。

无头与 CI

GOALSLOT_ACCESS_TOKEN 完全覆盖文件。如果你希望刷新正常工作，请将其与 GOALSLOT_REFRESH_TOKEN 配对；如果没有，刷新将被禁用，会话将在 1 小时访问令牌过期时结束。对于任何长期运行的任务，请改为设置 GOALSLOT_CONFIG_DIR，让服务器管理文件。

工具

九个读取工具和九个写入工具。读取工具可以自由调用，并带有 readOnlyHint 注释。每个写入工具的描述都以 WRITES. 开头，此处暴露的任何内容都不会删除用户数据。

读取

写入

刻意不提供的工具

删除目标、任务和时间条目；清除整个日程；公开或与他人共享任何内容；AI 教练聊天端点；计费和账户设置；模板导入。具有级联效应的破坏性操作以及任何发布个人数据的操作，都属于人类输入的地方，而不是代理可以循环调用的地方。请使用 GoalSlot 应用或 CLI。

工具强制执行的约定

• 时长是整数分钟，始终命名为 durationMinutes，绝不是裸的 duration。读取也返回 durationHours 作为浮点数，仅用于显示。目标的 targetHours 是唯一的例外。

• 日期为 YYYY-MM-DD，如果带有时间，则在边界处被拒绝。“今天”根据你的时区计算，而不是从 UTC ISO 切片中获取。

• 日程是重复的每周模板，不是带日期的活动。每个相关工具描述都如此说明。

• dayOfWeek 是周日优先（0 = 周日），这与每周报告使用的周一优先顺序不同。两者都在内联中标注，每个响应都带有 dayName。

• 每周桶是根据条目日期重新计算的，而不是从 API 存储的 dayOfWeek 列读取，该列在 API 服务器的时区中派生，可能相差一天。

错误

失败以 isError: true 返回，并带有一个 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。

技能

skills/ 中附带四个技能。它们承载了工具描述无法承载的判断：调用顺序、写入前要确认什么、以及不该说什么。

通过将目录复制到你的技能文件夹中，将它们安装到 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/ 中。

配置

HTTP 传输

可选，通过标志启用：

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

它在 http://127.0.0.1:7801/mcp 上通过流式 HTTP 传输提供相同的工具注册表，无状态。

这是仅限单用户和本地使用。每个请求都使用此机器的 GoalSlot 凭据提供服务。没有按调用方进行身份验证，没有 OAuth，也没有令牌托管，因此任何能够访问该端口的人都可以读写该账户。它绑定到 loopback，并且应保持如此。它不是 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 或更高版本。测试使用 vitest 并带有模拟的 fetch；套件中的任何内容都不会接触实时 API。CI 在 Ubuntu 和 Windows 上的 Node 20 和 22 上运行类型检查、测试和构建。

许可证

MIT