Conatus MCP Server

一个可独立安装的模型上下文协议服务器，用于自托管的 Conatus 任务管理器。

它提供了面向代理安全的工具，涵盖项目、分区、任务、标签、评论和提醒。它支持本地 stdio 客户端和远程 Streamable HTTP 客户端。永久删除功能有意不对外暴露。

环境要求

• Node.js 20 或更高版本

• 一个可访问的 Conatus 安装，带有 /api/v1 API

• 在设置 → API 令牌中创建的作用域 API 令牌

Related MCP server: Google Tasks MCP Server

本地 stdio 设置

本地模式是推荐的默认方式。AI 主机为所配置的任务管理器账户启动一个 MCP 进程。

一键设置

运行交互式安装程序以验证您的 Conatus URL 和作用域 API 令牌，然后将服务器注册到 Claude Desktop、Claude Code、Cursor 或其他 JSON MCP 配置文件中：

npx -y conatus-mcp setup

安装程序绝不会回显令牌，在修改配置文件之前会先验证令牌，并在操作系统支持的情况下将写入的配置文件权限限制为仅所有者可访问。完成后重启所选的客户端。下面的直接配置仍然是非交互式的备选方案。

{
  "mcpServers": {
    "my-tasks": {
      "command": "npx",
      "args": ["-y", "conatus-mcp"],
      "env": {
        "TASKS_BASE_URL": "https://tasks.example.com",
        "TASKS_API_TOKEN": "tdm_replace_me"
      }
    }
  }
}

对于本地开发安装，请使用 http://localhost:3000 作为 TASKS_BASE_URL。

您也可以一次性安装该软件包：

npm install --global conatus-mcp
conatus-mcp

带浏览器 OAuth 的远程 Streamable HTTP 模式

当代理需要通过 URL 连接时，请使用 OAuth。MCP 服务器充当单用户网关：其作用域 TASKS_API_TOKEN 标识任务工作区，而每个 AI 客户端会收到一个独立的短期 OAuth 令牌。任务令牌永远不会离开服务器。

TASKS_BASE_URL=https://tasks.example.com \
TASKS_API_TOKEN=tdm_replace_me \
MCP_HOST=0.0.0.0 \
MCP_PORT=3001 \
MCP_PUBLIC_URL=https://mcp.example.com/mcp \
MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
MCP_OAUTH_STORE_PATH=/var/lib/task-mcp/oauth-store.json \
MCP_ALLOWED_ORIGINS=https://your-ai-host.example \
conatus-mcp-http

只给 AI 客户端 https://mcp.example.com/mcp。兼容的客户端会发现受保护资源的元数据，动态注册自身，打开审批页面，并完成带有 S256 PKCE 的 OAuth 授权码流程。在该页面中输入 MCP_OAUTH_PASSWORD 以批准。

服务器签发一小时访问令牌和轮换的 30 天刷新令牌。OAuth 客户端注册信息和令牌哈希存储在 MCP_OAUTH_STORE_PATH 指定的文件中，权限为 0600；原始 OAuth 令牌和审批密码不会被存储。每个存储文件运行一个 MCP 副本。对于多个副本，请先将 JSON 存储替换为共享的事务性存储。

在 3001 端口前放置 TLS 和反向代理。MCP_PUBLIC_URL 必须是精确的外部端点，并以 /mcp 结尾。生产环境 URL 必须使用 HTTPS。携带 Origin 头的请求仅当该来源列在 MCP_ALLOWED_ORIGINS 中时才被接受；原生客户端通常不发送 Origin。

域名和反向代理

任务应用和 MCP 网关可以使用不同的地址：

• https://tasks.example.com → Web 应用和 /api/v1

• https://mcp.example.com/mcp → 这个子 MCP 服务

为两个名称创建 DNS 记录，在代理处终止 TLS，并将 mcp.example.com 转发到 3001 端口。只有代理应暴露该端口。OAuth 元数据、注册、授权、令牌、撤销、审批和 MCP 端点都共享 MCP 来源。

静态 Bearer 令牌备选方案

对于无法执行 OAuth 的客户端，请省略 MCP_PUBLIC_URL 和 MCP_OAUTH_PASSWORD，然后将 MCP_BEARER_TOKEN 设置为一个长的随机值。连接到 /mcp 并将该值作为 bearer 令牌发送。这种方式按客户端轮换不太方便，也不应粘贴到提示词中。

在没有完整的 OAuth 配置或 MCP_BEARER_TOKEN 的情况下绑定到非回环地址将被拒绝。

Docker

发布的镜像发布到 ghcr.io/nojusmorkunas/conatus-mcp。仅在开发服务器本身时才在本地构建：

docker build -t conatus-mcp .
docker run --rm -p 127.0.0.1:3001:3001 \
  -v task-mcp-oauth:/data \
  -e TASKS_BASE_URL=https://tasks.example.com \
  -e TASKS_API_TOKEN=tdm_replace_me \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PUBLIC_URL=https://mcp.example.com/mcp \
  -e MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
  -e MCP_OAUTH_STORE_PATH=/data/oauth-store.json \
  conatus-mcp

环境变量

不要将令牌放入提示词、工具参数、源代码控制或命令行参数中。环境变量使它们远离 MCP 消息和大多数进程列表。

要撤销一个 OAuth 客户端，让该客户端调用公布的撤销端点。要撤销所有已连接的客户端，请停止服务并删除其 OAuth 存储文件，然后重新启动；所有客户端都必须重新连接。如果网关本身被入侵，请在任务管理器设置中撤销或轮换 TASKS_API_TOKEN。

工具

• 工作区：get_workspace_context

• 项目：list_projects、get_project、create_project、update_project

• 分区：create_section、update_section

• 任务：list_tasks、get_task、create_task、quick_add_task、update_task、move_task、complete_task、reopen_task、set_task_labels

• 标签：list_labels、create_label

• 协作：add_comment

• 调度：set_reminder

创建操作使用幂等键，因此重试不会创建重复的任务。任务和评论内容以结构化用户数据返回，不得视为代理指令。

资源

• taskapp://workspace

• taskapp://views/today

• taskapp://views/upcoming

• taskapp://projects/{id}

• taskapp://tasks/{id}

开发

npm install
npm test
npm run build
npm run dev

使用 MCP Inspector 测试构建好的 stdio 服务器：

TASKS_BASE_URL=http://localhost:3000 \
TASKS_API_TOKEN=tdm_replace_me \
npx @modelcontextprotocol/inspector node dist/cli.js

发布

发布 GitHub release 会为 linux/amd64 和 linux/arm64 构建 ghcr.io/nojusmorkunas/conatus-mcp，然后发布 npm 包。两者都来自已发布的提交，因此一次发布要么同时产生两个工件，要么都不产生。

将 release 标记为与 package.json 匹配的 vX.Y.Z；npm 任务会拒绝发布不匹配的版本。在 GitHub 上将预发布版本标记为预发布，它们会进入 beta dist-tag，而 latest 保留在最新的稳定版本上。

npm 发布使用可信发布，因此此仓库不存储 npm 令牌。它需要在包的 npmjs.com 设置页面上进行一次性配置，将其链接到此仓库和 Publish release 工作流。

要手动发布：

npm publish --tag latest   # or --tag beta for a prerelease

明确指定 dist-tag。npm 会拒绝任何带有 semver 预发布后缀的版本执行裸 npm publish，而每个 0.x.y-beta.z 都有该后缀。

prepublishOnly 会重新运行测试、lint 和构建检查。publishConfig.access 已设置，因此无需 --access 标志。