使用说明

克劳德代码MCP服务器

为Claude Code定制MCP服务器：电报、Gmail、WhatsApp、日历和电子邮件。接线模式、配置和已知故障模式——从生产调试中编写。

服务器注册表

服务器	类型	位置	需要标记	状态
电报	频道（推送+工具）	`~/.claude/channels/telegram/`	`--dangerously-load-development-channels server:telegram`	活跃
gmail	工具服务器（仅拉取）	`~/.claude/channels/gmail/`	无	活动
whatsapp	频道（推送+工具）	`~/.claude/channels/whatsapp/`	`--dangerously-load-development-channels server:whatsapp`	活跃
日历	工具服务器（仅拉取）	`~/.claude/channels/calendar/`	无	活动
电子邮件	工具服务器（仅拉取）	`~/.claude/channels/email/`	无	活动

渠道与工具服务器

两种MCP服务器。不同的接线。

工具服务器 --克劳德按要求给他们打电话。注册于 ~/.claude.json 在...之下 mcpServers。每次会议均可立即使用。没有启动标志。Gmail是一个工具服务器。

通道服务器 --他们将通知推送到会话中（传入消息、事件）。相同的注册 ~/.claude.json，但需要启动标志，或者Claude Code会默默地忽略它们的通知。Telegram和WhatsApp是渠道服务器。

服务器既可以推送通知，也可以公开工具（回复、反应等）。Telegram和WhatsApp做到了这一点。渠道能力(experimental: { 'claude/channel': {} })是触发标志要求的原因。

配置

~/.claude.json--mcpServers块

{
  "mcpServers": {
    "telegram": {
      "type": "stdio",
      "command": "bash",
      "args": ["~/.claude/channels/telegram/telegram-start.sh"],
      "env": {}
    },
    "gmail": {
      "type": "stdio",
      "command": "bash",
      "args": ["~/.claude/channels/gmail/gmail-start.sh"],
      "env": {}
    },
    "whatsapp": {
      "type": "stdio",
      "command": "bash",
      "args": ["~/.claude/channels/whatsapp/whatsapp-start.sh"],
      "env": {}
    },
    "calendar": {
      "type": "stdio",
      "command": "bash",
      "args": ["~/.claude/channels/calendar/calendar-start.sh"],
      "env": {}
    },
    "email": {
      "type": "stdio",
      "command": "bash",
      "args": ["~/.claude/channels/email/email-start.sh"],
      "env": {}
    }
  }
}

添加新服务器

claude mcp add <name> --scope user -- bash ~/.claude/channels/<name>/<name>-start.sh

删除服务器

claude mcp remove <name> --scope user

初创公司

标准启动（所有渠道+工具）

claude --dangerously-load-development-channels server:telegram server:whatsapp

Gmail、日历和电子邮件会自动加载，无需任何标记。

通过代理

claude --dangerously-load-development-channels server:telegram server:whatsapp --agent orchestrator

严重： 如果代理人的前台有 tools 字段中，必须明确列出MCP工具，否则它们将被默默地排除在外。看代理商接线.

别名

alias claude-all='claude --dangerously-load-development-channels server:telegram server:whatsapp'
alias claude-all-orch='claude --dangerously-load-development-channels server:telegram server:whatsapp --agent orchestrator'

代理商接线

使用时 --agent，代理的frontmatter控制工具访问。

规则

tools 现场出席→ 允许名单。只有列出的工具可用。除非列出，否则不包括MCP工具。
disallowedTools 现场出席→ 拒绝名单。除列出的工具外，所有继承的工具。
无字段→ 继承的所有工具，包括MCP。

向代理添加MCP工具

在代理人的正面（例如。， .claude/agents/orchestrator.md):

---
name: orchestrator
description: ...
tools:
  # built-in tools
  - Read
  - Write
  - Edit
  - Bash
  - Agent
  # ... other built-in tools ...
  # MCP tools — wildcard per server
  - mcp__telegram__*
  - mcp__gmail__*
  - mcp__whatsapp__*
  - mcp__calendar__*
  - mcp__email__*
---

通配符模式： mcp__<server-name>__* 授予该服务器的所有工具。

具体工具： mcp__telegram__reply 仅授予回复工具。

如果添加新的MCP服务器，您还必须将其工具添加到每个需要它们的代理中。这是最常见的接线故障。

已知故障模式

1.官方插件冲突（关键）

症状： 电报409冲突错误。两个进程轮询相同的机器人令牌。

原因： 克劳德·科德派遣了一名官员 telegram 通过市场插件。如果已安装，它将与您的自定义竞争 telegram 用于机器人轮询槽的MCP服务器。

修复：

claude plugin uninstall telegram

然后验证插件条目是否已从 ~/.claude.json:

grep -n '"plugin": "telegram"' ~/.claude.json

如果仍然存在，请手动删除 {"marketplace": "claude-plugins-official", "plugin": "telegram"} 块。

危险： Claude Code更新可能会重新启用或重新安装官方插件。每次升级后，请检查：

grep '"plugin": "telegram"' ~/.claude.json

2.消息到达，但工具不可用

症状： ← telegram · user: Test 出现，但克劳德说“回复工具不可用。”

原因（最常见）： 代理frontmatter有 tools allowlist不包括MCP工具。看代理商接线.

原因（不太常见）： 会话未启动 --dangerously-load-development-channels通道通知可能仍然通过MCP连接流动，但工具被抑制。

原因（罕见）： MCP工具描述超过了2KB上限（v2.1.86引入）。检查：

# Count instruction bytes in server source
grep -oP 'instructions:\s*[`'"'"'"](.+?)[`'"'"'"]' server.ts | wc -c

3.claude.ai连接器碰撞

症状： 本地MCP服务器间歇性工作或工具出现重复。

原因： 与claude.ai连接器和本地MCP服务器（如Gmail）连接的相同服务。v2.1.86重复数据消除——本地获胜——但连接器仍显示“需要身份验证”，可能会产生干扰。

修复： 断开本地运行的任何服务的claude.ai连接器：

在克劳德代码中： /mcp → 找到claude.ai连接器→ 断开
或者通过CLI：使用以下命令检查可用选项 claude connector --help

规则： 每个服务一条路径。claude.ai连接器或本地MCP服务器。从来没有两者。

4.启动脚本权限

症状： 中列出的服务器 ~/.claude.json 但不会产卵。没有可见的进程。

原因： 启动脚本缺少执行权限。Claude Code运行它们 bash，所以 +x 不是严格要求的，但某些版本可能会使用 exec 这需要它。

修复：

chmod +x ~/.claude/channels/*/start*.sh

5.僵尸投票过程

症状： 409即使删除了官方插件，Telegram上仍存在冲突。

原因： 前一个会话的服务器进程仍在运行，正在进行轮询。

修复：

pkill -f telegram-start
pkill -f "server.ts"
pkill -f "server.mjs"
# Verify
ps aux | grep -E "(telegram|gmail|whatsapp|calendar|email)" | grep -v grep

然后重新启动Claude Code。

6.WhatsApp会话到期

症状： WhatsApp服务器启动，但显示“等待聊天”或二维码提示。

原因： whatsapp-web.js 会话中 .wwebjs_auth/ 过期（手机离线时间过长，或Meta推送了Web版本更新）。

修复： 删除会话并重新配对。QR码会打印到stderr，MCP的stdio传输会捕获它，因此从Claude code启动时您不会看到它。请改为独立运行：

rm -rf ~/.claude/channels/whatsapp/.wwebjs_auth/
cd ~/.claude/channels/whatsapp && node server.mjs 2>&1
# QR prints directly to terminal — scan immediately (expires in ~20s)
# Once paired, kill it (Ctrl-C), then start Claude Code normally.
# Session persists in .wwebjs_auth/ — no QR needed again unless it expires.

7.Gmail OAuth令牌到期

症状： Gmail服务器已连接，但所有工具调用都返回身份验证错误。

原因： OAuth刷新令牌已过期或被吊销。

修复：

# Re-run the auth flow to get a fresh refresh token:
./gmail-start.sh --auth

升级后检查表

每次Claude Code版本更新后运行：

# 1. Check version
claude --version

# 2. Check for re-installed official plugins
grep '"plugin": "telegram"' ~/.claude.json && echo "WARNING: official telegram plugin re-appeared — remove it"

# 3. Verify MCP server entries still exist
cat ~/.claude.json | python3 -c "
import sys, json
d = json.load(sys.stdin)
servers = d.get('mcpServers', {})
for name in ['telegram', 'gmail', 'whatsapp', 'calendar', 'email']:
    status = 'OK' if name in servers else 'MISSING'
    print(f'  {name}: {status}')
"

# 4. Check startup script permissions
ls -la ~/.claude/channels/*/start*.sh

# 5. Test each server manually
cd ~/.claude/channels/telegram && bash telegram-start.sh 2>&1 | head -5
cd ~/.claude/channels/gmail && bash gmail-start.sh 2>&1 | head -5
cd ~/.claude/channels/whatsapp && bash whatsapp-start.sh 2>&1 | head -5
cd ~/.claude/channels/calendar && bash calendar-start.sh --check
cd ~/.claude/channels/email && bash email-start.sh --check

# 6. Start session and verify tools
claude --dangerously-load-development-channels server:telegram server:whatsapp
# Inside session: /mcp → check all servers show tools

文件结构

~/.claude/
├── claude.json                    # MCP server registry (mcpServers block)
├── channels/
│   ├── telegram/
│   │   ├── server.ts              # MCP server (channel + tools)
│   │   ├── telegram-start.sh      # startup script (loads secrets from pass)
│   │   ├── package.json
│   │   ├── access.json            # runtime state (allowlist, groups, pending)
│   │   ├── debug.log
│   │   └── node_modules/
│   ├── gmail/
│   │   ├── server.ts              # MCP server (tools only, no channel)
│   │   ├── auth.ts                # one-time OAuth2 authorization
│   │   ├── gmail-start.sh         # startup script (loads secrets from pass)
│   │   ├── package.json
│   │   └── node_modules/
│   ├── whatsapp/
│   │   ├── server.mjs             # MCP server (channel + tools)
│   │   ├── whatsapp-start.sh      # startup script
│   │   ├── package.json
│   │   ├── access.json
│   │   ├── debug.log
│   │   ├── inbox/                 # downloaded media
│   │   ├── .wwebjs_auth/          # puppeteer session (auto-created)
│   │   └── node_modules/
│   ├── calendar/
│   │   ├── server.ts              # MCP server (tools only — CalDAV + Cal.com)
│   │   ├── calendar-start.sh      # startup script
│   │   ├── package.json
│   │   ├── debug.log
│   │   └── node_modules/
│   └── email/
│       ├── server.ts              # MCP server (tools only — IMAP + SMTP/Resend)
│       ├── email-start.sh         # startup script
│       ├── package.json
│       ├── debug.log
│       └── node_modules/
├── secrets/
│   ├── secret.sh                  # GPG-encrypted credential manager
│   └── README.md                  # setup and usage docs
└── agents/                        # (project-level agents reference MCP tools in frontmatter)

秘密

所有凭据都存储在 pass （GPG加密 ~/.password-store/).由...管理 secrets/secret.sh.

安全模型

服务器在启动时通过生成来加载机密 secret.sh get <channel> <key> 通过 spawnSync凭据存储在本地TypeScript中 const 变量——从不在 process.env.

层	克劳德可以访问吗？
`~/.password-store/*.gpg`	否——GPG加密
`process.env` 运行时	否--secrets不在env中
`/proc/<pid>/environ`	不，没什么可读的
TypeScript堆变量	否--没有文件系统暴露

启动脚本只传递 SECRET_CMD 路径（to secret.sh)作为env变量，服务器将其从中删除 process.env 加载机密后立即。

设置

# One-time: install pass + GPG
sudo apt install pass gnupg
gpg --gen-key
pass init <gpg-key-id>

# Store credentials per server
./secrets/secret.sh set calendar caldav-url "https://..."
./secrets/secret.sh set calendar caldav-username "user@example.com"
./secrets/secret.sh set calendar caldav-password "app-password"

./secrets/secret.sh set email imap-host "imap.fastmail.com"
./secrets/secret.sh set email imap-user "user@example.com"
./secrets/secret.sh set email imap-pass "app-password"
./secrets/secret.sh set email smtp-host "smtp.fastmail.com"

# Or use interactive setup
./calendar/calendar-start.sh --configure
./email/email-start.sh --configure

用于MCP启动的GPG缓存

Claude Code将启动脚本作为没有TTY的子流程生成。启动前先对GPG缓存进行预充：

pass show claude-calendar/caldav-url > /dev/null && claude

存储布局

~/.password-store/
  claude-telegram/
    bot-token.gpg
    admin-id.gpg
  claude-gmail/
    client-id.gpg
    client-secret.gpg
    refresh-token.gpg
  claude-calendar/
    caldav-url.gpg
    caldav-username.gpg
    caldav-password.gpg
    calcom-api-key.gpg        # optional
    calcom-base-url.gpg        # optional
  claude-email/
    imap-host.gpg
    imap-port.gpg
    imap-user.gpg
    imap-pass.gpg
    smtp-host.gpg              # optional if using Resend
    smtp-port.gpg
    smtp-user.gpg
    smtp-pass.gpg
    smtp-from.gpg
    resend-api-key.gpg         # optional alternative to SMTP
    resend-from.gpg

添加新的通道服务器

新通道接线检查表：

构建服务器位于 ~/.claude/channels/<name>/
创建启动脚本： <name>-start.sh
设置权限： chmod +x <name>-start.sh
注册： claude mcp add <name> --scope user -- bash ~/.claude/channels/<name>/<name>-start.sh
添加到代理前台： mcp__<name>__* 在每个代理人的 tools 需要它的列表
添加到启动别名： 更新 claude-all 别名与 server:<name>
先进行无试剂测试： 确认工具出现在 /mcp
使用试剂进行测试： 确认工具仍然出现
文档在此注册表中

添加新工具服务器

与上述相同，除了：

不 --dangerously-load-development-channels 需要旗帜
不 server:<name> 在启动别名中
服务器从以下位置自动启动 ~/.claude.json 注册
仍然需要 mcp__<name>__* 在代理frontmatter如果使用 --agent

版本历史记录

日期	版本	问题	解决方案
2026-03-21	~2.1.8x	电报未收到消息	丢失 `--dangerously-load-development-channels` 旗帜
2026-03-21	~2.1.8x	409电报冲突	官方插件与自定义服务器竞争-- `claude plugin uninstall telegram`
2026-03-28	2.1.86	所有MCP工具不可用	v2.1.83中的权限修复重新启用了官方插件→v2.1.86；代理前台 `tools` 所有缺失的MCP条目
2026-03-28	2.1.86	Gmail连接器冲突	claude.ai Gmail连接器+本地服务器=去重冲突。规则：每个服务一条路径

使用说明

克劳德代码MCP服务器

服务器注册表

渠道与工具服务器

配置

~/.claude.json--mcpServers块

添加新服务器

删除服务器

初创公司

标准启动（所有渠道+工具）

通过代理

别名

代理商接线

规则

向代理添加MCP工具

已知故障模式

1.官方插件冲突（关键）

2.消息到达，但工具不可用

3.claude.ai连接器碰撞

4.启动脚本权限

5.僵尸投票过程

6.WhatsApp会话到期

7.Gmail OAuth令牌到期

升级后检查表

文件结构

秘密

安全模型

设置

用于MCP启动的GPG缓存

存储布局

添加新的通道服务器

添加新工具服务器

版本历史记录

相关 MCP

MCP服务器生成工具

MCP服务器安装工具

OpenAPI工具服务器

游戏开发工具集线器

计算器模块模板

模型上下文协议SDK