dear-claude

亲爱的 Claude

一个 MCP 服务，可从外部平台触发本地 Claude Code 实例。
在 Linear、GitHub、Jira、GitLab、Notion 或 Obsidian 中说一声“亲爱的 Claude”——Claude Code 实例就会启动并处理任务。

你的笔记化为架构。你的任务化为拉取请求。

---

这是什么？

Dear Claude 是一个 MCP（Model Context Protocol）服务，会监视你的项目管理工具，查找短语 “Dear Claude”。检测到后，它会启动一个本地 Claude Code 实例，以便：

• 读取问题／评论／笔记的上下文
• 执行所请求的任务（编写代码、审查、创建任务等）
• 将结果发回原平台
• 将会话保留 7 天，以便进行多轮对话

**无需 Anthropic API 密钥。**可使用你现有的 Claude Code 订阅。100% 本地且私密——你的代码绝不会离开你的设备。

支持的平台

平台	在问题／PR 上触发	在评论中触发	回帖	表情反应	子任务	PR／MR 审查
GitHub	是	是	是	是	-	是
Linear	是	是	是	是	是	-
Jira	是	是	是	-	是	-
GitLab	是	是	是	是	-	是
Notion	是	是	是	-	-	-
Obsidian	是	-	是	-	-	-

跨平台编排

来自任何平台的实例都可以访问所有已配置平台的 API。这可以实现如下工作流：

1. 在 Obsidian 中编写规范 → “亲爱的 Claude，在 Linear 中创建这些任务”
2. 在 Linear 上讨论 → “亲爱的 Claude，在 GitHub 上编写此代码”
3. 在 GitHub 上审查 → “亲爱的 Claude，解决这些合并冲突”
4. 并行编码 → Claude 启动多个实例，每个分支对应一个实例，并使用 git worktrees

快速开始

一行安装

claude mcp add dear-claude -- bunx dear-claude start --mcp

就这样。启动 Claude Code，Dear Claude 即可使用。

前置条件

• 已安装 Claude Code CLI（可用 claude 命令）
• Bun 运行时（用于 bunx）
• 已启用 Funnel 的 Tailscale（用于接收外部平台的 Webhook）

手动设置（替代方式）

如果你更喜欢手动配置，请在 ~/.claude.json 的 mcpServers 下添加：

{
  "mcpServers": {
    "dear-claude": {
      "command": "bunx",
      "args": ["dear-claude", "start", "--mcp"],
      "env": {
        "DEAR_CLAUDE_PORT": "3334",
        "GITHUB_CLIENT_ID": "...",
        "GITHUB_CLIENT_SECRET": "...",
        "GITHUB_WEBHOOK_SECRET": "...",
        "LINEAR_CLIENT_ID": "...",
        "LINEAR_CLIENT_SECRET": "...",
        "LINEAR_WEBHOOK_SECRET": "..."
      }
    }
  }
}

然后启动 Claude Code：

claude

MCP 服务会自动启动、设置 Tailscale Funnel，并显示你的公开 Webhook URL。

---

平台设置

Tailscale Funnel

Dear Claude 使用 Tailscale Funnel 获取稳定的公开 HTTPS URL，以接收 Webhook。设置过程大多会自动完成。

1. 安装 Tailscale：

   # macOS
   brew install tailscale
   
   # Linux
   curl -fsSL https://tailscale.com/install.sh | sh
   

2. 进行身份验证：tailscale up

3. 在管理控制台中启用 Funnel：https://login.tailscale.com/admin/acls

   • 在 ACL 策略中添加 "funnel" 功能

4. 服务启动时会自动配置 Funnel。你的公开 URL 为：

   https://<your-hostname>.ts.net/dc
   

提示：运行 tailscale serve status --json 以验证配置。健康检查每 10 秒自动修复一次 Funnel 配置。

---

GitHub

选项 A：GitHub App（推荐）

1. 前往 GitHub Settings → Developer settings → GitHub Apps → New GitHub App
2. 设置以下字段：
   • Homepage URL：https://<your-hostname>.ts.net/dc
   • Callback URL：https://<your-hostname>.ts.net/dc/oauth/callback/github
   • Webhook URL：https://<your-hostname>.ts.net/dc/webhook/github
   • Webhook secret：生成一个随机字符串
3. 在 Permissions 下：
   • 仓库：Issues（读取与写入）、Pull Requests（读取与写入）、Contents（读取与写入）
4. 在 Subscribe to events 下：
   • Issue 评论、Pull request review 评论
5. 复制凭据并设置环境变量：

   GITHUB_CLIENT_ID=Iv1.abc123...
   GITHUB_CLIENT_SECRET=abc123...
   GITHUB_WEBHOOK_SECRET=your-webhook-secret
   

6. 在你的仓库上安装此应用
7. 完成 OAuth：访问 https://<your-hostname>.ts.net/dc/setup/github

选项 B：Personal Access Token（更简单，无 Webhook）

1. 前往 GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. 创建一个具有以下范围的令牌：repo、write:discussion
3. 设置：GITHUB_ACCESS_TOKEN=ghp_...

注意：仅使用 PAT 不会触发由 Webhook 启动的实例。你可以改用 spawn_instance MCP 工具或 /api/spawn 端点。

环境变量	说明
GITHUB_CLIENT_ID	GitHub App 客户端 ID
GITHUB_CLIENT_SECRET	GitHub App 客户端密钥
GITHUB_WEBHOOK_SECRET	Webhook 签名验证密钥
GITHUB_ACCESS_TOKEN	个人访问令牌（OAuth 的替代方式）

---

Linear

1. 前往 Linear Settings → API → OAuth Applications → New Application
2. 设置回调 URL：https://<your-hostname>.ts.net/dc/oauth/callback/linear
3. 复制 Client ID 和 Client Secret
4. 在 OAuth 应用中启用 Webhooks 开关
5. 前往 Linear Settings → API → Webhooks → New Webhook：
   • URL：https://<your-hostname>.ts.net/dc/webhook/linear
   • 复制 Signing Secret
   • 启用事件：Comments（创建）、Issues（创建、更新）
6. 设置环境变量：

   LINEAR_CLIENT_ID=your-client-id
   LINEAR_CLIENT_SECRET=your-client-secret
   LINEAR_WEBHOOK_SECRET=your-signing-secret
   

7. 完成 OAuth：访问 https://<your-hostname>.ts.net/dc/setup/linear

完成 OAuth 后，只有来自你已通过身份验证的 Linear 账户的 issue/评论才会触发 Claude。

替代方式：在 Linear Settings → Account → API 中使用个人 API 密钥（LINEAR_ACCESS_TOKEN=lin_api_...）。

环境变量	说明
LINEAR_CLIENT_ID	OAuth 客户端 ID
LINEAR_CLIENT_SECRET	OAuth 客户端密钥
LINEAR_WEBHOOK_SECRET	Webhook 签名密钥
LINEAR_ACCESS_TOKEN	个人 API 密钥（OAuth 的替代方式）

---

Jira Cloud

1. 在 https://id.atlassian.com/manage-profile/security/api-tokens 创建 API 令牌
2. 设置环境变量：

   JIRA_DOMAIN=mycompany              # Your Jira subdomain (mycompany.atlassian.net)
   [email protected]    # Your Atlassian account email
   JIRA_API_TOKEN=ATATT3x...          # The API token you just created
   JIRA_WEBHOOK_SECRET=optional-secret # Optional shared secret
   

3. 在 Jira 中创建 Webhook：
   • 前往 Jira Admin → System → Webhooks → Create webhook
   • URL：https://<your-hostname>.ts.net/dc/webhook/jira
     • 如果使用 JIRA_WEBHOOK_SECRET，请追加：?secret=YOUR_SECRET
   • 选择事件：issue_created、issue_updated、comment_created
4. 保存 Webhook

Claude 可以通过 Jira REST API v2 创建子任务、变更 issue 状态并添加评论。

环境变量	说明
JIRA_DOMAIN	Jira 子域名（例如，mycompany.atlassian.net 中的 mycompany）
JIRA_USER_EMAIL	你的 Atlassian 邮箱
JIRA_API_TOKEN	Atlassian 提供的 API 令牌
JIRA_WEBHOOK_SECRET	用于 Webhook 验证的可选共享密钥

---

GitLab

1. 在 GitLab → Settings → Access Tokens 中创建个人访问令牌
   • 范围：api、read_repository、write_repository
2. 设置环境变量：

   GITLAB_ACCESS_TOKEN=glpat-...
   GITLAB_WEBHOOK_SECRET=your-secret
   

3. 为你的项目（或群组）添加 Webhook
   • 前往 Settings → Webhooks
   • URL：https://<your-hostname>.ts.net/dc/webhook/gitlab
   • 密钥令牌：与 GITLAB_WEBHOOK_SECRET 相同
   • 触发事件：Comments、Issues events、Merge request events
4. 保存

对于自托管的 GitLab，还需设置 GITLAB_URL=https://your-gitlab-instance.com。

环境变量	说明
GITLAB_ACCESS_TOKEN	个人访问令牌
GITLAB_WEBHOOK_SECRET	Webhook 密钥令牌
GITLAB_URL	GitLab 实例 URL（默认值：https://gitlab.com）

---

Notion

选项 A：内部集成（更简单）

1. 前往 https://www.notion.so/my-integrations → New integration
2. 为集成命名并选择你的工作区
3. 复制 Internal Integration Secret
4. 设置：NOTION_ACCESS_TOKEN=ntn_...
5. 与集成共享页面/数据库（点击页面上的 "..." → Connections → Add your integration）

选项 B：OAuth（公共应用）

1. 在 https://www.notion.so/my-integrations 创建 OAuth 集成
2. 设置回调 URL：https://<your-hostname>.ts.net/dc/oauth/callback/notion
3. 设置环境变量：

   NOTION_CLIENT_ID=your-client-id
   NOTION_CLIENT_SECRET=your-secret
   

4. 完成 OAuth：访问 https://<your-hostname>.ts.net/dc/setup/notion

Webhook 设置

Notion 目前还没有原生 Webhook。要从 Notion 触发 Claude：

• 使用 Notion 的自动化规则和 Webhook 操作（如果可用）
• 或使用 Zapier/Make 等第三方服务，向 https://<your-hostname>.ts.net/dc/webhook/notion 发送 POST 请求
• 如果需要验证签名，请设置 NOTION_WEBHOOK_SECRET

环境变量	说明
NOTION_ACCESS_TOKEN	内部集成令牌
NOTION_CLIENT_ID	OAuth 客户端 ID
NOTION_CLIENT_SECRET	OAuth 客户端密钥
NOTION_WEBHOOK_SECRET	Webhook 验证密钥

---

Obsidian

Obsidian 集成通过文件系统监视实现——无需 Webhook。Claude 会监视你的库，查找包含 "Dear Claude" 的文件，并通过追加内容到同一文件来回复。

1. 设置环境变量，指定库的绝对路径：

   OBSIDIAN_VAULT_PATH=/Users/yourname/Documents/MyVault
   

2. 就是这样！在任意 .md 文件中写下 "Dear Claude, ..." 并保存。

Claude 的回复会以提示块的形式追加到同一篇笔记中。Frontmatter 中会添加 claude-status 字段（processing → done / error）。

工作原理：

• 监视库中 .md 文件的更改
• 忽略 .obsidian/、.trash/ 和点文件目录中的文件
• 采用 2 秒防抖，避免每次按键都触发
• 支持 Wikilink 引用（[[other-note]]）——Claude 会解析并读取这些引用
• 支持嵌入图像——Claude 可以查看和分析图像

环境变量	说明
OBSIDIAN_VAULT_PATH	Obsidian 库的绝对路径
OBSIDIAN_WATCH_DEBOUNCE_MS	防抖延迟，单位为毫秒（默认值：2000）

---

使用方法

触发格式

在以下任意位置写下 "Dear Claude"（不区分大小写，中间有空格）：

• GitHub issue/PR 评论
• Linear issue 描述或评论
• Jira issue 描述或评论
• GitLab issue/MR 描述或评论
• Notion 页面评论
• Obsidian .md 文件

示例

GitHub PR 评论：

Dear Claude, please review this code for bugs and security issues.

Claude 在 GitHub 上的回复：

Claude 实例已启动（实例：abc12345） 正在处理你的请求……

任务已完成 发现 2 个问题：

1. user.ts:45 存在 SQL 注入风险
2. api.ts:102 缺少输入验证

已创建包含修复的 PR #15。

实例编排

Claude 实例可以生成其他实例来并行处理任务：

Dear Claude, code tasks 1-5 in parallel. Each task should be a separate branch.

Claude 将：

1. 解析任务
2. 通过 /api/spawn 端点生成 5 个子实例
3. 每个子实例在自己的 git worktree 中工作（同一仓库，不同分支）
4. 每个子实例完成后都会创建 PR
5. 父实例轮询子实例状态

---

所有环境变量

# Server
DEAR_CLAUDE_PORT=3334
TAILSCALE_HOSTNAME=              # Optional: auto-detected

# GitHub
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_WEBHOOK_SECRET=
GITHUB_ACCESS_TOKEN=

# Linear
LINEAR_CLIENT_ID=
LINEAR_CLIENT_SECRET=
LINEAR_WEBHOOK_SECRET=
LINEAR_ACCESS_TOKEN=

# Jira Cloud
JIRA_DOMAIN=mycompany
[email protected]
JIRA_API_TOKEN=
JIRA_WEBHOOK_SECRET=

# GitLab
GITLAB_ACCESS_TOKEN=
GITLAB_WEBHOOK_SECRET=
GITLAB_URL=                      # Default: https://gitlab.com

# Notion
NOTION_CLIENT_ID=
NOTION_CLIENT_SECRET=
NOTION_WEBHOOK_SECRET=
NOTION_ACCESS_TOKEN=

# Obsidian
OBSIDIAN_VAULT_PATH=
OBSIDIAN_WATCH_DEBOUNCE_MS=2000

# Optional
GIPHY_API_KEY=                   # For fun GIF reactions in responses

CLI 命令

# Start the server (standalone mode)
bun run src/index.ts start

# Start as MCP server (stdio, for Claude Code)
bun run src/index.ts start --mcp

# Check server and platform status
bun run src/index.ts status

# List instances
bun run src/index.ts instances

# Setup instructions for a platform
bun run src/index.ts setup <platform>

MCP 工具

在 Claude Code 中作为 MCP 服务运行时，可以使用以下工具：

工具	描述
list_platforms	列出已配置的平台及其状态
list_instances	列出所有 Claude 实例（可按状态筛选）
get_instance_status	获取指定实例的详细状态
get_instance_messages	获取实例的对话历史
kill_instance	终止正在运行的实例
get_running_instances	列出当前正在运行的实例 ID
spawn_instance	为任务生成新的 Claude 实例
get_project_instances	列出项目组中的所有实例

HTTP API

服务器还会在 localhost:3334 上公开 REST 端点：

端点	方法	描述
/health	GET	健康检查 + 平台状态
/webhook/:platform	POST	Webhook 接收端
/api/instances	GET	列出实例（?project_id= 筛选器）
/api/instances/:id	GET	获取实例详情 + 子实例
/api/instances/:id/kill	POST	终止正在运行的实例
/api/spawn	POST	以编程方式生成新实例
/api/platforms	GET	列出已配置的平台
/setup/:platform	GET	启动 OAuth 流程
/oauth/callback/:platform	GET	OAuth 回调

POST /api/spawn

{
  "prompt": "Implement the login page",
  "repo_url": "https://github.com/owner/repo",
  "branch": "feature/login",
  "base_branch": "main",
  "parent_instance_id": "optional-parent-id",
  "project_id": "optional-project-id"
}

架构

                  Webhooks / File Watcher
  ┌────────┐ ┌────────┐ ┌──────┐ ┌────────┐ ┌──────────┐ ┌────────┐
  │ GitHub │ │ Linear │ │ Jira │ │ GitLab │ │ Obsidian │ │ Notion │
  └───┬────┘ └───┬────┘ └──┬───┘ └───┬────┘ └────┬─────┘ └───┬────┘
      │          │         │         │            │            │
      └──────────┴────┬────┴─────────┴────────────┴────────────┘
                      │
                      ▼
           ┌─────────────────────┐
           │  Tailscale Funnel   │
           │ (Public HTTPS URL)  │
           └─────────┬───────────┘
                     │
                     ▼
           ┌─────────────────────┐
           │   dear-claude       │
           │   MCP Server        │
           │                     │
           │ • Trigger detection │
           │ • Instance manager  │
           │ • Platform adapters │
           │ • Spawn API         │
           │ • SQLite DB         │
           └─────────┬───────────┘
                     │
                     ▼
           ┌─────────────────────┐
           │  Claude Code        │
           │  Instances          │
           │ (Agent SDK)         │
           │                     │
           │ • Git worktrees     │
           │ • Cross-platform    │
           │   API access        │
           │ • Child spawning    │
           └─────────────────────┘

实例生命周期

PENDING → RUNNING → IDLE → (follow-up) → RUNNING → IDLE → ... → EXPIRED (7 days)
                  ↘ COMPLETED
                  ↘ FAILED

• PENDING：检测到触发事件，实例已排队
• RUNNING：Claude Code 正在处理
• IDLE：等待后续的 “Dear Claude” 提及
• COMPLETED：任务成功完成
• FAILED：发生错误
• EXPIRED：超过 7 天 TTL，实例已清理

开发

# Install dependencies
bun install

# Run dev mode
bun run dev

# Type check
bunx tsc --noEmit

# Build
bun run build

# Run tests
bun test

故障排除

Tailscale

• “Tailscale 未运行”：打开 Tailscale 应用（macOS），或运行 sudo systemctl start tailscaled && tailscale up（Linux）
• “Funnel 未启用”：访问 https://login.tailscale.com/admin/acls 并添加 Funnel 功能
• Funnel 消失：其他 tailscale serve/tailscale funnel 命令可能覆盖了它。健康检查会在 10 秒内自动修复。使用 tailscale serve status --json 验证。

Webhook

• 未触发：检查 bun run src/index.ts status，确认服务器已启动。使用 curl https://<your-hostname>.ts.net/dc/health 测试。
• “签名无效”：确认平台配置和环境变量中的 Webhook 密钥一致。
• GitHub：此应用订阅 issue_comment 事件。若要通过新 PR 触发，请发布评论；仅 PR 描述不会触发。

OAuth

• 令牌已过期：重新访问 https://<your-hostname>.ts.net/dc/setup/<platform> 进行身份验证。
• 401 错误：存储的 OAuth 令牌可能已被撤销。删除 data/dear-claude.db 中失效的令牌，然后重新进行身份验证。

实例

• 卡在 PENDING 状态：检查 Claude Code CLI（claude）是否已安装，并可通过 PATH 访问。
• 工作目录问题：实例会在 data/workspaces/ 下创建工作区。请确保有写入权限。

能力证明

此仓库随附一份 smithmark 能力清单 smithmark.yaml，以及一份静态工具列表 tools.json。该清单在一处声明了此 MCP 服务运行时涉及的全部外部范围：

• 网络出站：它访问的所有主机（api.github.com、github.com、api.linear.app、linear.app、gitlab.com、*.atlassian.net、api.notion.com、api.giphy.com、api.anthropic.com）及其用途。
• 文件系统：它读取或写入的路径（~/.dear-claude/**、data/**、~/.claude.json、调试日志）及访问级别。
• 执行：它启动的子进程（claude、tailscale、which、open、sudo、pkill）。
• 环境变量和机密：它使用的所有凭据类环境变量，并按类型标记（访问令牌、客户端机密、webhook 机密、API 密钥、私钥）。

每次发布 GitHub 版本时，.github/workflows/smithmark-attest.yml 都会对已发布的 npm tarball 生成 无密钥 Sigstore 证明：GitHub 的 OIDC 令牌会交换为短期 Fulcio 签名证书，证明使用该证书签名，签名随后记录在公开的 Rekor 透明日志中。整个过程不涉及签名密钥或机密。生成的 smithmark-attestation.sigstore.json 会附加到 GitHub 版本发布中。

验证已发布的版本：

smithmark verify [email protected] \
  --certificate-identity "https://github.com/sns45/dear-claude/.github/workflows/smithmark-attest.yml@refs/tags/v1.1.0" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

（将 v1.1.0 替换为实际的版本标签）

此清单是本服务能力范围的 权威 记录。smithmark 的 lint 有意不感知主机，仅提供参考：它会将每个 fetch() 调用点和每次执行都标记为“未声明”，不论清单中包含什么，因此即使上述出站访问已完整声明，它也会在此代码库（以及任何真实的 MCP 服务）中报告问题。在 --strict 或感知主机的后继版本发布之前，请将 lint 输出视为发现问题的辅助工具，而非偏差信号。

许可证

MIT