使用说明

Zoho MCP服务器

用于Zoho项目和WorkDrive集成的模型上下文协议（MCP）服务器。

📖 目录

🚀 快速入门指南
⚙️ 高级配置
🛠 可用工具
💻 使用示例
🧪 发展
🚀 部署
🔍 故障排除

概述

⚡ 5分钟内开始使用Zoho Projects API！

该服务器通过与MCP兼容的客户端（如Cursor IDE和Claude）实现与Zoho应用程序的自然语言交互。它通过JSON-RPC协议提供对Zoho项目任务和WorkDrive文件的安全访问。

🏠 推荐使用方法

🎯 强烈建议在当地使用！

✅ 个人发展与学习：当地环境最佳
✅ 原型设计：用于测试的安全开发环境
✅ 小团队：VPN环境中的使用有限
⚠️ 生产部署：需要高级安全配置

✨ 主要特点

🎯 轻松设置：5分钟OAuth设置和自动令牌管理
🔐 安全：JWT身份验证、IP分配、速率限制
🚀 快速：Redis缓存，异步处理
📊 全面的：任务管理、文件操作、项目分析
🤖 AI就绪：非常适合Cursor IDE、Claude和其他MCP客户端
🏠 本地优先：优先考虑在当地环境中的安全使用

🎬 你能做什么

📝 创建和管理任务 用自然语言
📊 生成项目报告 和分析
🔍 跨项目搜索 和文件
📁 上传/下载文件 转到WorkDrive
🔔 实时网络挂钩 用于任务更新

💡 用例建议

用例	推荐环境	安全级别
🧪 个人学习与发展	本地环境	基本设置
👥 小团队	本地+VPN	标准设置
🏢 企业使用	专用服务器+VPN	高级设置
🚀 生产服务	不推荐	-

项目结构

zoho-mcp-server/
├── server/                 # Main application code
├── tests/                  # Test suites
├── docs/                   # Documentation & guides
│   ├── requirement/        # Requirements documentation
│   ├── plan/               # Project planning documents
│   ├── design/             # Design documents
│   └── guides/             # Setup guides & troubleshooting
├── tools/                  # Development & utility scripts
├── config/                 # Configuration files
├── reports/                # Generated reports & project data
└── temp/                   # Temporary files

目录详细信息

server/ -主要应用程序代码（处理程序、身份验证、存储等）
tests/ -测试套件（单元、集成、e2e、安全）
docs/ -文件和指南
- guides/ -安装指南和故障排除文档
tools/ -开发工具、测试脚本和实用程序
config/ -配置模板和设置
reports/ -生成的任务报告、项目数据和导出（gitignored）
temp/ -临时文件（覆盖报告、日志等）

特性

第一阶段（MVP）

任务管理：在Zoho项目中创建、读取和更新任务
项目分析：获取完成率和进度摘要
文件操作：在WorkDrive中下载和上传文件
搜索：跨项目查找文件和任务
网页插件：任务更新的实时通知

安全

具有IP分配的JWT身份验证
速率限制（100要求/分钟）
CORS保护
OAuth2与Zoho的集成

🚀 快速入门指南

⏱️ 所需时间：约5分钟 | 💡 仅限初始设置 | 🏠 推荐当地环境

🎯 让我们先从当地环境开始！

本指南假定在本地环境中安全使用。如果您正在考虑生产部署，请检查危险分子第一。

🤖 MCP客户端设置（光标IDE/Claude桌面）

对于本地MCP使用，不需要JWT身份验证！ MCP服务器直接作为子进程运行。

🎯 光标IDE设置

安装MCP服务器 （按照以下安装步骤操作）
配置光标MCP设置:

创建或更新 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "zoho-mcp-server": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["-m", "server.mcp_stdio_server"],
      "env": {
        "PYTHONPATH": "/path/to/your/project/zoho-mcp-server",
        "ZOHO_CLIENT_ID": "your_client_id",
        "ZOHO_CLIENT_SECRET": "your_client_secret", 
        "ZOHO_REFRESH_TOKEN": "your_refresh_token",
        "ZOHO_PORTAL_ID": "your_portal_id",
        "REDIS_URL": "redis://localhost:6379/0",
        "REDIS_SSL": "false",
        "ALLOWED_IPS": "127.0.0.1,::1,localhost",
        "ENVIRONMENT": "development"
      },
      "cwd": "/path/to/your/project/zoho-mcp-server"
    }
  }
}

重新启动游标IDE 加载MCP服务器
测试连接 向Cursor询问您的Zoho项目

🎯 Claude桌面设置

安装MCP服务器 （按照以下安装步骤操作）
配置克劳德桌面MCP设置:

创建或更新 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "zoho-mcp-server": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["-m", "server.mcp_stdio_server"],
      "env": {
        "PYTHONPATH": "/path/to/your/project/zoho-mcp-server",
        "ZOHO_CLIENT_ID": "your_client_id",
        "ZOHO_CLIENT_SECRET": "your_client_secret",
        "ZOHO_REFRESH_TOKEN": "your_refresh_token", 
        "ZOHO_PORTAL_ID": "your_portal_id",
        "REDIS_URL": "redis://localhost:6379/0",
        "REDIS_SSL": "false",
        "ALLOWED_IPS": "127.0.0.1,::1,localhost",
        "ENVIRONMENT": "development"
      },
      "cwd": "/path/to/your/project/zoho-mcp-server"
    }
  }
}

对于Windows： %APPDATA%/Claude/claude_desktop_config.json 对于Linux： ~/.config/Claude/claude_desktop_config.json

重新启动克劳德桌面 加载MCP服务器
测试连接 向克劳德询问你的Zoho项目

💡 MCP设置的重要注意事项

无需JWT：MCP客户端将服务器作为子进程运行，因此不需要身份验证令牌
使用完整路径：始终使用绝对路径 command 和 cwd
虚拟环境：确保使用虚拟环境中的Python可执行文件
环境变量：所有Zoho证书必须在 env 章节
需要Redis：确保Redis在本地运行(brew services start redis macOS）

🧙‍♂️ 选项A：自动设置（推荐）

最简单的方法！Wizard自动化了一切：

# 1. Install dependencies
pip install -r requirements-dev.txt

# 2. Run setup wizard
python tools/setup_wizard.py

向导会自动执行以下操作：

✅ 先决条件检查（Python、Redis）
✅ .env文件创建
✅ JWT_SECRET自动生成
✅ Zoho身份验证设置
✅ OAuth身份验证流程
✅ 门户ID和项目ID检索
✅ 最终测试

5分钟内完成！ 🎉

📖 选项B：手动设置

为那些想了解细节的人提供手动设置：

📋 先决条件

Python 3.12+ （带pip）
Redis服务器 （建议本地安装）
Zoho账户 （项目和WorkDrive访问）
当地发展环境 （macOS、Windows、Linux）

🔧 步骤1：安装

克隆和设置:

git clone <repository-url>
cd zoho-mcp-server
pip install -r requirements-dev.txt

启动Redis （本地服务器）：

# macOS (Homebrew) - recommended
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis

# Windows (WSL recommended) 
sudo service redis-server start

# Docker (cross-platform)
docker run -d -p 6379:6379 redis:alpine

🔐 步骤2:Zoho OAuth设置

选择以下方法之一：

🌟 方法A：自动设置（推荐）

创建Zoho应用程序:
- 首选 Zoho API控制台
- 点击“添加客户”→ “基于服务器的应用程序”
- 填写：
  - 客户名称: MCP Server
  - 你的家园: http://localhost:8000
  - 授权重定向URI: http://localhost:8000/auth/callback
配置环境:

cp config/env.example .env

编辑 .env 文件 使用您的Zoho证书：

# Required: Copy from Zoho API Console
ZOHO_CLIENT_ID=1000.XXXXXXXXXXXXXXXXXX
ZOHO_CLIENT_SECRET=your_client_secret_here

# JWT Secret (ONLY required for web server deployment, NOT for MCP usage)
# JWT_SECRET=your_generated_jwt_secret_here  # Comment out for MCP usage

# Required: Your Portal ID (see step 5.2 below)
ZOHO_PORTAL_ID=your_portal_id

# Required: Default Project ID for testing (see step 5.3 below)
TARGET_PROJECT_ID=your_project_id_here

# Redis (default for local)
REDIS_URL=redis://localhost:6379/0

3.1.生成JWT密钥 （仅适用于web服务器部署）：

# Skip this step for MCP usage!
# python tools/generate_jwt_secret.py

⚠️ 用于MCP使用：不需要JWT，跳过此步骤
✅ 对于web服务器：自动生成安全的JWT_SECRET

启动服务器 （当地环境）：

# Local environment startup (recommended)
uvicorn server.main:app --host 127.0.0.1 --port 8000 --reload

# Or to allow external access (caution required)
uvicorn server.main:app --host 0.0.0.0 --port 8000 --reload

运行OAuth身份验证 （自动设置）：

python tools/generate_zoho_auth_url.py

选择选项 1 （推荐，自动设置）
遵循浏览器身份验证
✅ 完成！ 刷新令牌会自动保存

测试您的设置:

# Quick verification
python tools/verify_setup.py

# Test API access (optional)
python tools/get_project_tasks.py

✅ 如果成功，您将看到您的项目和任务！

📖 方法B：手动设置（自助客户端）

无需服务器配置即可进行更简单的设置：

使用自助客户端:
- 首选 Zoho API控制台
- 点击“自助客户端”选项卡
- 选择范围： ZohoProjects.projects.read, ZohoProjects.tasks.all
- 生成代码（10分钟到期）
转换为刷新令牌:

python tools/exchange_auth_code.py "YOUR_GENERATED_CODE"

⚙️ 步骤3：初始设置验证

基本设置验证:

python tools/verify_setup.py

🔍 步骤4：查找您的门户和项目ID

获取您的门户ID和可用项目:

python tools/get_real_portal_and_projects.py

📋 将显示可用项目列表
📝 记下门户ID和项目ID

更新 .env 带有您ID的文件:

# Edit .env file and update the following:
ZOHO_PORTAL_ID=your_actual_portal_id
TARGET_PROJECT_ID=your_actual_project_id

✅ 第五步：最终测试

完成API测试:

python tools/get_project_tasks.py

✅ 如果成功，将显示项目任务列表

备选方案：使用特定项目进行测试:

python tools/get_project_tasks.py --project-id YOUR_PROJECT_ID

🎯 第六步：开始使用

🎉 本地环境设置完成！ 您的MCP服务器现已准备就绪！服务器提供：

MCP端点: http://127.0.0.1:8000/mcp （仅限本地）
健康检查: http://127.0.0.1:8000/health
API文件: http://127.0.0.1:8000/docs （调试模式）

🔄 重要：OAuth认证后の必须手顺

OAuth认证完成后请务必重新启动服务器：

# 1. 現在のサーバーを停止 (Ctrl+C)
# 2. サーバーを再起動
uvicorn server.main:app --host 127.0.0.1 --port 8000 --reload

理由：新建Refresh Token重新启动交互渲染

🛡️ 安全说明

✅ 本地使用：最安全和推荐的使用方法
⚠️ 外部访问：需要高级安全配置(详情)
🔒 敏感数据：从不共享.env文件
🏠 开发环境：在单独的环境中管理生产数据
🔄 OAuth之后：始终在身份验证后重新启动服务器

🔧 快速故障排除

❌ “OAuth作用域无效”错误

# Remove problematic scope and retry
python tools/generate_zoho_auth_url.py
# Select option 1 and re-authenticate

❌ “重定向Uri无效”错误

# Check Zoho API Console settings:
# Redirect URI must be: http://localhost:8000/auth/callback

❌ Redis连接错误

# Check Redis is running
redis-cli ping
# Should return: PONG

❌ JWT_SECRET缺失或无效 （仅限Web服务器）

# For MCP usage: JWT is NOT required, comment out JWT_SECRET in .env
# For web server: Generate new JWT secret
python tools/generate_jwt_secret.py

❌ “JWT_SECRET太短”错误 （仅限Web服务器）

# For MCP usage: Comment out JWT_SECRET in .env file
# For web server: JWT_SECRET must be at least 32 characters
python tools/generate_jwt_secret.py

有关详细的故障排除，请参阅： docs/guides/

⚙️ 高级配置

环境变量引用

变量	描述	必填	默认
`ZOHO_CLIENT_ID`	Zoho OAuth客户端ID	✅ 是	-
`ZOHO_CLIENT_SECRET`	Zoho OAuth客户端密码	✅ 是	-
`ZOHO_REFRESH_TOKEN`	OAuth刷新令牌（自动生成）	✅ 是	-
`ZOHO_PORTAL_ID`	您的Zoho门户ID	⚠️ 推荐	-
`JWT_SECRET`	JWT签名密钥（仅适用于web服务器，不适用于MCP）	❌ 否（适用于MCP）	-
`REDIS_URL`	Redis连接URL	✅ 是的	`redis://localhost:6379/0`
`ALLOWED_IPS`	IP地址列表（逗号分隔）	❌ 没有	`127.0.0.1,::1`
`RATE_LIMIT_PER_MINUTE`	请求速率限制	❌ 没有	`100`
`DEBUG`	启用调试模式	❌ 没有	`false`

所需Zoho示波器

自动配置以下范围：

ZohoProjects.projects.read -阅读项目信息
ZohoProjects.tasks.all -完全任务管理访问权限

附加设置指南

📖 OAuth详细指南: docs/guides/zoho_oauth_setup_guide.md
🔧 自客户端方法: docs/guides/zoho_self_client_setup.md
🔍 故障排除: docs/guides/fix_400_error_guide.md

API终点

MCP协议

POST /mcp -JSON-RPC 2.0端点
GET /manifest.json -工具清单

健康与监测

GET /health -健康检查
POST /webhook/task-updated Webhook 接收器

🛠 可用工具

工具	说明	参数
`listTasks`	列出项目任务	`project_id`, `status?`
`createTask`	创建新任务	`project_id`, `name`, `owner?`, `due_date?`
`updateTask`	更新现有任务	`task_id`, `status?`, `due_date?`, `owner?`
`getTaskDetail`	获取任务详细信息	`task_id`
`getProjectSummary`	获取项目指标	`project_id`, `period?`
`downloadFile`	下载WorkDrive文件	`file_id`
`uploadReviewSheet`	上传审核文件	`project_id`, `folder_id`, `name`, `content_base64`
`searchFiles`	搜索文件	`query`, `folder_id?`

💻 使用示例

列出任务

{
  "jsonrpc": "2.0",
  "method": "callTool",
  "params": {
    "name": "listTasks",
    "arguments": {
      "project_id": "123456789",
      "status": "open"
    }
  },
  "id": "1"
}

创建任务

{
  "jsonrpc": "2.0", 
  "method": "callTool",
  "params": {
    "name": "createTask",
    "arguments": {
      "project_id": "123456789",
      "name": "Review API documentation",
      "owner": "developer@company.com",
      "due_date": "2025-07-01"
    }
  },
  "id": "2"
}

🧪 发展

测试

# Run all tests
pytest

# Run with coverage
pytest --cov=server --cov-report=html

# Run specific test types
pytest tests/unit/
pytest tests/integration/
pytest tests/e2e/

代码质量

# Linting
ruff check .
ruff format .

# Type checking  
mypy server/

# Security scan
bandit -r server/
safety check

预提交钩子

pre-commit install
pre-commit run --all-files

🚀 部署

⚠️ 重要：确保在部署到生产环境之前完成安全配置！

🚨 安全警告

按原样部署渲染是危险的！ 任何人都可以访问您的Zoho帐户。

必需：阅读渲染生产安全设置指南第一。

渲染平台（安全配置后）

完整的安全配置 - 安全指南
将您的GitHub存储库连接到Render
在Render仪表板中配置环境变量（遵循安全指南）
推送到主分支时自动部署

🔒 生产环境变量（必需的安全配置）

# Security configuration (required)
ENVIRONMENT=production
DEBUG=false
LOG_LEVEL=WARNING
ALLOWED_IPS=your.office.ip,your.home.ip  # Allow only your IPs
JWT_SECRET=your_128_character_super_secure_secret  # 128 characters recommended
JWT_EXPIRE_HOURS=1  # Short expiration time

# Zoho configuration
ZOHO_CLIENT_ID=your_zoho_client_id
ZOHO_CLIENT_SECRET=your_zoho_client_secret  
ZOHO_REFRESH_TOKEN=your_zoho_refresh_token
ZOHO_PORTAL_ID=your_portal_id
TARGET_PROJECT_ID=your_project_id

# Enhanced security
RATE_LIMIT_PER_MINUTE=20  # Strict rate limiting

🚀 JWT代币生成（用于生产）

# Generate token for team member
python tools/generate_jwt_token.py generate --user "team_member_1" --expires-hours 24

# For temporary access
python tools/generate_jwt_token.py generate --user "temp_access" --expires-hours 1

# Token validation
python tools/generate_jwt_token.py validate "your_jwt_token_here"

码头工人

# Build image
docker build -t zoho-mcp-server .

# Run container (with security configuration)
docker run -p 8000:8000 --env-file .env zoho-mcp-server

特定环境配置

生产（增强安全性）

使用Render Starter计划或更高版本
配置带有身份验证的Redis插件
设置监控和警报
启用自动缩放
需要IP限制和JWT身份验证

发展

使用本地Redis实例
启用调试模式
使用开发Zoho凭据
本地IP分配列表配置

监控

健康检查

/health 基本健康状况终点
Redis连接检查
Zoho API可访问性测试

指标

请求率和响应时间
按端点划分的错误率
令牌刷新频率
缓存命中率

日志记录

结构化JSON日志记录
请求/响应相关ID
安全事件跟踪
性能指标

安全

身份验证流程

客户端请求JWT令牌（外部进程）
包含 Authorization: Bearer <token> 头球
服务器验证JWT签名和过期
根据列表检查IP地址
每个客户适用的费率限制

OAuth令牌管理

到期前自动刷新令牌
使用TTL在Redis中进行安全存储
令牌撤销支持
在secrets管理器中刷新令牌备份

🔍 故障排除

常见问题

401未经授权

检查JWT令牌的有效性和过期时间
验证JWT_SECRET与令牌颁发者匹配
确认IP地址在列表中

429价格有限

降低请求频率
检查速率限制标头
考虑请求批处理

Zoho API错误

验证OAuth范围和权限
检查刷新令牌有效性
监测Zoho API利率限制

Redis连接问题

验证Redis URL和凭据
检查网络连接
监控Redis内存使用情况

调试模式

集 DEBUG=true 在环境中实现：

详细的错误消息
API请求/响应日志记录
API交互式文档，网址： /docs

贡献

分叉存储库
创建要素分支
通过测试进行更改
进行质量检查
提交拉取请求

开发工作流程

遵循常规提交消息
保持90%+的测试覆盖率
更新API变更文档
安全扫描所有依赖项

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

GitHub错误报告问题
文档 docs/ 目录
API参考 /docs 端点（调试模式）