nestr

@nestr/mcp

适用于 Nestr 的 MCP（Model Context Protocol）服务——将 Claude 等 AI 助手连接到你的工作区。

这是什么？

此 MCP 服务可让 AI 助手与 Nestr 工作区交互：

• 搜索任务、项目和角色
• 创建和更新 nest
• 查看组织结构（圈子、角色、职责）
• 获取工作区洞察和指标
• 添加评论并协作

快速开始

访问 mcp.nestr.io，按照分步说明轻松完成设置，适用于 Claude Desktop、Claude Code 和 Cursor。

Claude Desktop

1. 前往 设置 → 连接器 → 添加自定义连接器
2. 将 名称 设为 Nestr，将 远程 MCP URL 设为 https://mcp.nestr.io/mcp
3. 点击“添加”，然后点击“验证身份”，使用 Nestr 登录

Claude Code

claude mcp add nestr --transport http https://mcp.nestr.io/mcp

然后在 Claude Code 中运行 /mcp，并点击“验证身份”进行登录。

使用 npm 包（本地）

如果你希望在本地运行 MCP 服务：

npx @nestr/mcp

使用以下配置设置 AI 客户端：

{
  "mcpServers": {
    "nestr": {
      "command": "npx",
      "args": ["-y", "@nestr/mcp"],
      "env": {
        "NESTR_API_KEY": "your-api-key-here"
      }
    }
  }
}

获取 API 密钥：

1. 前往你的 Nestr 工作区
2. 点击 设置 → 集成 → 工作区 API 访问权限 → 配置
3. 点击 “新建 API 密钥” 并复制密钥

开始使用

你可以向 AI 助手提出以下问题：

• “我可以访问哪些工作区？”
• “搜索与营销相关的任务”
• “创建一个名为 ‘Q1 Planning’ 的新项目”
• “我当前有哪些项目？它们的状态如何？”
• “谁负责客户支持？”

可用工具

工作区与搜索

工具	描述
nestr_list_workspaces	列出可访问的工作区
nestr_get_workspace	获取工作区详情
nestr_create_workspace	创建新工作区（仅限 OAuth）
nestr_search	搜索 nest（任务、项目、角色）
nestr_get_me	获取当前用户身份和工作区列表

Nests（任务、项目、角色）

工具	描述
nestr_get_nest	获取指定 nest 的详情（支持使用逗号分隔的 ID 批量获取；单个 nest 可使用 provenance/rights/whoCan 标记）
nestr_explain_nest	诊断单个 nest：字段/属性的来源（由哪个标签/圈子定义）、调用者组合后的权限及拒绝追踪，以及（使用 whoCan 时）谁可以对其执行操作、应联系谁
nestr_get_nest_children	获取子 nest
nestr_create_nest	创建新 nest
nestr_update_nest	更新 nest 属性
nestr_delete_nest	删除 nest
nestr_reorder_nest	将 nest 相对于另一个 nest 重新排序
nestr_bulk_reorder	批量调整多个 nest 的顺序
nestr_add_label	为 nest 添加标签
nestr_remove_label	从 nest 移除标签

重复安排

工具	描述
nestr_set_recurrence	设置或移除任务、项目或会议的重复规则
nestr_list_occurrences	列出某个系列的所有实例，包括虚拟实例和已物化实例；每个实例都包含下方工具所需的 instant
nestr_skip_occurrence	跳过一个实例但不结束系列；或者使用 scope: "following" 删除该实例及其后的所有实例
nestr_update_occurrence	编辑一个实例；如果它仍是虚拟实例，则先将其物化
nestr_delete_series	删除整个系列，包括过去的实例

评论与讨论

工具	描述
nestr_add_comment	为 nest 添加评论
nestr_get_comments	获取 nest 上的评论/讨论
nestr_get_nest_activity	查看 nest 及其下级发生的变更，并将每项变更作为数据返回
nestr_update_comment	更新评论
nestr_delete_comment	删除评论

组织结构

工具	描述
nestr_list_circles	列出组织圈
nestr_get_circle	获取圈详情
nestr_get_circle_roles	获取圈内角色及其职责和领域
nestr_list_roles	列出所有角色
nestr_list_users	列出工作区成员
nestr_get_user	获取用户详情
nestr_add_workspace_user	将用户添加到工作区并向其发送邀请邮件（API 配置需要经过验证的域名；应用内邀请则不需要）

张力

工具	描述
nestr_create_tension	在圈或角色上创建张力
nestr_get_tension	获取张力详情
nestr_list_tensions	列出圈或角色上的张力
nestr_update_tension	更新张力
nestr_delete_tension	删除张力
nestr_get_tension_parts	获取张力的提案部分
nestr_add_tension_part	添加提案部分（新增或变更的治理事项）
nestr_modify_tension_part	修改提案部分
nestr_remove_tension_part	移除提案部分
nestr_get_tension_part_children	获取提案部分的子项（职责／领域）
nestr_create_tension_part_child	为提案部分添加子项
nestr_update_tension_part_child	更新提案部分的子项
nestr_delete_tension_part_child	删除提案部分的子项
nestr_get_tension_changes	预览提案部分将应用的差异
nestr_get_tension_status	获取张力的投票状态
nestr_update_tension_status	提交投票或撤回为草稿

图链接

工具	描述
nestr_get_graph_links	获取通过命名关系关联的 nest（例如，会议议程事项）
nestr_add_graph_link	在两个 nest 之间创建双向链接
nestr_remove_graph_link	移除两个 nest 之间的链接

标签和项目

工具	描述
nestr_list_labels	列出工作区标签
nestr_get_label	获取标签详情
nestr_get_projects	列出项目及其状态

洞察和应用

工具	描述
nestr_get_insights	获取工作区指标
nestr_get_insight_history	获取指标的历史趋势数据
nestr_get_workspace_apps	列出已启用的应用／功能

个人（仅限 OAuth）

工具	描述
nestr_get_me	获取当前用户身份和工作区
nestr_list_inbox	列出用户收件箱中的项目
nestr_create_inbox_item	快速捕捉到收件箱
nestr_get_inbox_item	获取收件箱项目详情
nestr_update_inbox_item	更新收件箱项目
nestr_reorder_inbox	重新排列收件箱项目
nestr_list_personal_labels	列出用户的个人标签
nestr_create_personal_label	创建个人标签
nestr_get_daily_plan	获取标记为今天的项目
nestr_add_to_daily_plan	将项目添加到今天的重点事项
nestr_remove_from_daily_plan	从今天的重点事项中移除项目
nestr_list_my_tensions	列出由你创建或分配给你的张力
nestr_list_tensions_awaiting_consent	列出需要你投票的治理提案

MCP Apps（交互式界面）

MCP Apps 是可嵌入支持该功能的 MCP 客户端（如 Claude.ai）的交互式 UI 组件。它们为使用 Nestr 数据提供丰富的可视化界面。

可完成列表

资源 URI： ui://nestr/completable-list

用于查看和完成任务与项目的交互式列表。

功能：

• 项目显示方框图标，待办事项显示复选框
• 勾选项目即可将其标记为已完成（删除线）
• 支持行内编辑标题（自动保存）
• 支持拖放排序
• 显示父级路径，便于了解上下文
• 提供快速链接，可在 Nestr 中打开项目

**用法：**当 AI 助手返回任务或项目结果时，支持此功能的客户端可以显示此交互式界面，而不是纯文本，让你可以直接在聊天中完成项目、编辑标题和重新排序。

身份验证

OAuth（推荐）

托管服务 mcp.nestr.io 会自动处理 OAuth。只需添加服务，然后通过浏览器完成身份验证。

OAuth 会遵循用户权限，因此 AI 助手只能访问已通过身份验证的用户有权访问的内容。

API 密钥

API 密钥可访问整个工作区，并适用于本地 npm 包。请参阅上文的快速入门。

**注意：**无论用户权限如何，API 密钥都可访问整个工作区。

环境变量

身份验证（必需）

变量	说明
NESTR_API_KEY	Nestr API 密钥（可访问整个工作区）
NESTR_OAUTH_TOKEN	OAuth 令牌（遵循用户权限）

* 本地使用时，必须设置 NESTR_API_KEY 或 NESTR_OAUTH_TOKEN。

配置（可选）

变量	说明	默认值
NESTR_API_BASE	API 基础 URL	https://app.nestr.io/api

托管／服务端（仅限 HTTP 传输）

运行用于托管部署的 HTTP 服务端时会用到这些变量：

变量	说明	默认值
PORT	HTTP 服务端端口	3000
NESTR_OAUTH_CLIENT_ID	用于托管 OAuth 流程的 OAuth 客户端 ID	-
NESTR_OAUTH_CLIENT_SECRET	OAuth 客户端密钥	-
OAUTH_ENCRYPTION_KEY	用于静态加密 OAuth 会话的 32 字节 base64 密钥	-
GTM_ID	落地页的 Google Tag Manager 容器 ID	-

分析（可选）

服务端分析选项：

GA4 Measurement Protocol：

变量	说明
GA4_MEASUREMENT_ID	GA4 Measurement ID（例如：G-XXXXXXXXXX）
GA4_API_SECRET	Measurement Protocol API 密钥
GA4_DEBUG	设置为 true 可验证事件，但不记录事件

**注意：**GA4 跟踪需要同时设置 GA4_MEASUREMENT_ID 和 GA4_API_SECRET。如果只设置了测量 ID，系统会记录警告并禁用跟踪。

MCPcat（MCP 专用分析）：

变量	说明
MCPCAT_PROJECT_ID	MCPcat 项目 ID（来自 mcpcat.io）
MCPCAT_ENABLE_REPLAY	启用会话回放（默认值：false）

开发

# Clone the repository
git clone https://github.com/nestr-dev/nestr-mcp.git
cd nestr-mcp

# Install dependencies
npm install

# Set your API key
export NESTR_API_KEY=your-api-key

# Run in development mode (stdio)
npm run dev

# Run HTTP server for local testing
npm run dev:http

# Build for production
npm run build

# Test with MCP Inspector
npm run inspect

安全

SECURITY.md 是完整的政策说明：如何报告漏洞、三种授权面分别可访问哪些内容，以及此服务端会存储和不会存储哪些内容。要点如下：

• 切勿将 API 密钥或 OAuth 令牌提交到版本控制中
• OAuth 令牌会遵循用户权限，因此推荐使用
• API 密钥可访问整个工作区；如需细粒度权限，请使用 OAuth
• 对于只需读取数据的集成，请使用 /mcp/readonly

凭证有效期与轮换

OAuth 令牌会过期，并会自动为你刷新。服务端会将刷新令牌与会话一同保存，并在访问令牌即将过期时续期，因此长期运行的客户端无需重新授权也能继续工作。在 Nestr 中撤销会话后，下一次刷新将失败，访问权限也会随之失效。无需手动轮换。

**API 密钥不会过期。**工作区 API 密钥会一直有效，直到工作区管理员在 Nestr 的 Settings > Integrations > Workspace API access 中将其撤销。因此，轮换工作由你负责，而不是服务端：

• 任何有权访问密钥的人离开时进行轮换，并按你设定的时间安排定期轮换
• 撤销不再使用的密钥，而不是让它们继续留存——未使用的密钥仍是可用的工作区级凭证
• 如果密钥可能已泄露，请立即轮换
• 签发只读密钥，并在集成只需读取数据时将其指向 /mcp/readonly

资源

• 设置指南 - 分步设置说明
• Nestr 帮助中心
• Nestr API 文档
• Model Context Protocol

许可证

MIT - 参见 LICENSE

支持

• GitHub 问题
• Nestr 支持