语雀 MCP 代理服务器

语雀 Model Context Protocol (MCP) 代理服务器，让 AI 助手能够通过 MCP 协议与语雀平台交互。

兼容性: 支持所有符合 MCP 标准的客户端，包括 Chatbox、Claude Desktop、Cherry Studio、Cursor 等主流工具。

✨ 功能特性

• 🔌 MCP 协议支持 - 完全兼容 Model Context Protocol 2024-11-05
• 🌐 多客户端支持 - 支持 Chatbox、Claude Desktop、Cherry Studio、Cursor 等主流工具
• 🪟 跨平台支持 - 支持 macOS、Linux 和 Windows 系统
• 📚 知识库管理 - 创建、读取、更新、删除知识库
• 📄 文档管理 - 完整的文档 CRUD 操作
• 🔍 搜索功能 - 全文搜索、高级搜索
• 👥 用户管理 - 获取用户信息、团队管理
• 🔐 安全配置 - 支持 HTTP Header 和环境变量配置 Token
• 🚀 自动启动 - 支持系统服务自动启动（macOS launchd / Windows Service）

📋 支持的工具

用户相关

• get_user_info - 获取当前用户信息
• get_user - 获取指定用户信息

知识库管理

• list_repos - 列出所有知识库
• list_user_repos - 列出指定用户的知识库
• get_repo - 获取知识库详情
• create_repo - 创建知识库
• update_repo - 更新知识库信息
• delete_repo - 删除知识库
• get_repo_toc - 获取知识库目录
• update_repo_toc - 更新知识库目录

文档管理

• list_docs - 列出知识库中的文档
• get_doc - 获取文档内容
• create_doc - 创建文档
• update_doc - 更新文档
• delete_doc - 删除文档
• list_doc_versions - 列出文档版本历史

搜索功能

• search_docs - 搜索文档

团队管理（需要团队权限）

• list_groups - 列出团队
• get_group - 获取团队信息
• list_group_users - 列出团队成员
• list_group_repos - 列出团队知识库
• ... 等更多功能

🚀 快速开始

方式一：Docker 部署（推荐）

# 1. 克隆项目
git clone https://github.com/your-username/yuque-mcpserver.git
cd yuque-mcpserver

# 2. 设置 Token
export YUQUE_TOKEN=your-token-here

# 3. 启动服务
docker-compose up -d

# 4. 验证服务
curl http://localhost:3000/health

# 5. 运行自动化测试
./docker-test.sh

方式二：本地部署

1. 克隆项目

git clone https://github.com/your-username/yuque-mcpserver.git
cd yuque-mcpserver

2. 配置 Token

方式一：配置文件（推荐）

# 复制配置示例文件
cp yuque-config.env.example yuque-config.env

# 编辑配置文件，填入您的语雀 Token
nano yuque-config.env

方式二：环境变量

export YUQUE_TOKEN="your-token-here"

方式三：HTTP Header（Chatbox 配置）

在 Chatbox 的 MCP Server 配置中，HTTP Header 字段添加：

X-Yuque-Token=your-token-here

获取 Token：语雀设置 > 个人设置 > Token

3. 启动服务

# 启动服务
./start_server.sh start

# 查看状态
./start_server.sh status

4. 验证服务

# 健康检查
curl http://localhost:3000/health

📝 常用命令

# 启动服务
./start_server.sh start

# 停止服务
./start_server.sh stop

# 重启服务
./start_server.sh restart

# 查看状态
./start_server.sh status

# 查看日志
./start_server.sh logs

# 管理配置
./start_server.sh config

# 安装系统服务（macOS，可选）
./install_service.sh

⚙️ 配置说明

配置文件格式

yuque-config.env:

# 语雀 Token（必需）
YUQUE_TOKEN=your-token-here

# 服务端口（可选，默认 3000）
PORT=3000

配置优先级

1. HTTP Header (X-Yuque-Token) - 最高优先级
2. 环境变量 (YUQUE_TOKEN)
3. 配置文件 (yuque-config.env)

如果都未配置，系统会返回明确的错误提示。

🔧 系统服务（macOS）

如果您希望服务在系统启动时自动运行：

./install_service.sh

安装后，服务会在开机时自动启动，无需手动操作。

服务管理

# 启动服务
launchctl start com.yuque.mcp

# 停止服务
launchctl stop com.yuque.mcp

# 查看状态
launchctl list | grep com.yuque.mcp

📚 文档

详细文档请查看 docs/ 目录：

• docs/QUICK_START.md - 快速开始指南
• docs/CONFIG_GUIDE.md - 配置指南
• docs/DOCKER_DEPLOYMENT.md - Docker 部署指南（推荐）
• docs/AUTO_START_GUIDE.md - 自动启动指南（macOS）
• docs/WINDOWS_DEPLOYMENT.md - Windows 部署指南
• docs/CLIENT_COMPATIBILITY.md - 客户端兼容性指南（多工具配置）
• docs/YUQUE_API_REFERENCE.md - 语雀 API 接口文档（OpenAPI 规范）

🔒 安全提示

• ✅ 配置文件 yuque-config.env 已添加到 .gitignore，不会被提交到代码仓库
• ✅ 文件权限已设置为 600（仅所有者可读写）
• ⚠️ 请勿将 Token 提交到代码仓库
• ⚠️ 定期轮换 Token，确保安全

🐛 故障排查

服务无法启动

# 查看日志
./start_server.sh logs

# 或直接查看
tail -f /tmp/yuque-proxy.log

Token 配置问题

# 检查配置
./start_server.sh config

# 验证 Token
curl -H "X-Yuque-Token: your-token" http://localhost:3000/health

端口被占用

# 检查端口占用
lsof -i :3000

# 修改端口（在 yuque-config.env 中设置 PORT）

📊 API 端点

• POST /mcp - MCP 协议端点
• GET /health - 健康检查
• GET /test - 测试端点

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🙏 致谢

• 语雀 Open API
• Model Context Protocol

---

提示: 所有操作都在项目根目录中执行。