内容
# 📚 雅思 MCP 服务器
<div align="center">
**直接连接 Claude Desktop 到您的 Google Drive 雅思学习资料。**
无需下载任何文件到本地机器，即可阅读 PDF、DOCX 文件和 Google 文档。
</div>
---
## ✨ 功能特点
- 🔗 **直接访问 Google Drive** — 连接到您的 Drive 文件夹，无需下载文件
- 📄 **多格式支持** — PDF、DOCX、Google Docs、Google Sheets、TXT
- 🔍 **智能搜索** — 按文件名在整个 Drive 中查找文档
- 📁 **文件夹导航** — 浏览嵌套文件夹结构
- 🤖 **AI 驱动的分析** — 生成雅思练习题和提取词汇 *(需要 Azure OpenAI)*
- 📖 **内置雅思资源** — 评分标准、任务格式、写作标准
- 🎯 **可重复使用的提示** — 雅思辅导、论文反馈、问题生成器
---
## 🏗️ 架构
```
Claude Desktop
│ stdio (JSON-RPC 2.0)
▼
┌─────────────────────────────────┐
│ FastMCP 服务器 │
│ │
│ ┌─────────┐ ┌──────────────┐ │
│ │ 工具/ │ │ 资源/ │ │
│ │ │ │ │ │
│ │ gdrive │ │ ielts:// │ │
│ │ 本地 │ │ 评分标准 │ │
│ │ 分析 │ │ 任务类型 │ │
│ └────┬────┘ └──────────────┘ │
└───────┼─────────────────────────┘
│
┌────┴────────────────┐
│ │
▼ ▼
Google Drive Azure OpenAI
(OAuth 2.0) (可选)
```
---
## 📋 前置条件
- Python 3.11+
- [uv](https://docs.astral.sh/uv/) — 快速的 Python 包管理器
- [Claude Desktop](https://claude.ai/download)
- 具有 Drive 访问权限的 Google 账户
- 启用 Drive API 的 Google Cloud 项目
---
## 🚀 安装
### 1. 安装 uv
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### 2. 克隆并安装
```bash
git clone https://github.com/your-username/ielts-mcp-server.git
cd ielts-mcp-server
uv sync
```
这样就完成了 — `uv sync` 会自动创建虚拟环境并安装所有依赖项。无需手动创建 `venv` 或运行 `pip install`。
### 3. 配置环境
```bash
cp .env.example .env
```
编辑 `.env`:
```env
# 本地雅思文档路径（可选，如果不使用 Google Drive）
DOCUMENTS_DIR=./documents
# Azure OpenAI（可选，用于 AI 驱动的工具）
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_KEY=your-key-here
AZURE_OPENAI_DEPLOYMENT=gpt-4o
```
---
## 🔑 Google Drive 设置
### 步骤 1 — 创建 Google Cloud 项目
1. 访问 [Google Cloud 控制台](https://console.cloud.google.com)
2. 创建新项目
3. 导航到 **API 和服务 → 库**
4. 搜索 **Google Drive API** → 点击 **启用**
### 步骤 2 — 创建 OAuth 凭证
1. 导航到 **API 和服务 → 凭证**
2. 点击 **+ 创建凭证 → OAuth 2.0 客户端 ID**
3. 应用程序类型：**桌面应用程序**
4. 点击 **创建** → **下载 JSON**
### 步骤 3 — 安装凭证文件
重命名下载的文件为 `credentials.json` 并放置在以下位置：
```
# macOS / Linux
~/.ielts_mcp/credentials.json
# Windows
C:\Users\<your-username>\.ielts_mcp\credentials.json
```
```bash
# macOS / Linux
mkdir -p ~/.ielts_mcp
mv ~/Downloads/client_secret_*.json ~/.ielts_mcp/credentials.json
# Windows (PowerShell)
mkdir $env:USERPROFILE\.ielts_mcp
mv $env:USERPROFILE\Downloads\client_secret_*.json $env:USERPROFILE\.ielts_mcp\credentials.json
```
### 步骤 4 — 添加自己为测试用户
1. 导航到 **API 和服务 → OAuth 同意屏幕 → 受众**
2. 向下滚动到 **测试用户 → 添加用户**
3. 输入您的 Gmail 地址 → **保存**
---
## ⚙️ Claude Desktop 配置
查找配置文件：
| 操作系统 | 路径 |
|---|---|
| Windows | `%AppData%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
添加 `mcpServers` 键：
```json
{
"mcpServers": {
"ielts-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/ielts-mcp-server",
"run",
"ielts-mcp",
"--stdio"
]
}
}
}
```
**Windows 示例：**
```json
{
"mcpServers": {
"ielts-mcp": {
"command": "uv",
"args": [
"--directory",
"D:/python/tung_mcp",
"run",
"ielts-mcp",
"--stdio"
]
}
}
}
```
**macOS 示例：**
```json
{
"mcpServers": {
"ielts-mcp": {
"command": "uv",
"args": [
"--directory",
"/Users/yourname/ielts-mcp-server",
"run",
"ielts-mcp",
"--stdio"
]
}
}
}
```
> **为什么使用 `uv run`？** 它会自动使用项目的虚拟环境 — 无需查找可执行文件的确切路径，并且在所有平台上都能正常工作。
重启 Claude Desktop — 您应该会在聊天输入中看到 🔨 工具图标。
---
## 💬 使用方法
### 首次身份验证
在第一次工具调用时，会自动打开一个浏览器窗口：
```
Claude: "让我列出您的雅思文件..."
→ 浏览器打开 → 使用 Google 登录 → 允许访问
→令牌保存到 ~/.ielts_mcp/token.json
→ 从现在开始自动工作
```
### 示例提示
**浏览您的 Drive：**
```
列出我的雅思 Drive 文件夹中的所有文件
```
**阅读文档：**
```
阅读 Cambridge 20.pdf 并总结阅读段落
```
**生成练习题：**
```
阅读 IELTS Band 9 Vocab Secrets.pdf 并创建 10 张闪存卡
```
**获取写作反馈：**
```
阅读 cause_solution_task2.docx 并针对雅思写作标准进行分析
```
**搜索您的资料：**
```
在我的 Drive 中查找所有与写作任务 2 相关的文件
```
---
## 🛠️ 可用工具
| 工具 | 描述 |
|---|---|
| `gdrive_list_files` | 按关键词搜索 Drive 中的文件 |
| `gdrive_list_folder` | 列出特定文件夹中的所有文件 |
| `gdrive_read_file` | 读取 PDF、DOCX 或 Google 文档的内容 |
| `gdrive_search` | 按文件名搜索文件 |
| `list_documents` | 列出本地文件（需要 `DOCUMENTS_DIR`） |
| `read_document` | 读取本地 PDF、DOCX 或 TXT |
| `search_documents` | 按名称搜索本地文件 |
| `analyze_text` | 估计文本的雅思评分级别 *(需要 Azure OpenAI)* |
| `generate_questions` | 从段落中生成雅思风格的问题 *(需要 Azure OpenAI)* |
| `extract_vocabulary` | 提取关键雅思词汇及其定义 *(需要 Azure OpenAI)* |
## 📖 可用资源
| URI | 描述 |
|---|---|
| `ielts://band-descriptors` | 1-9 级评分标准 |
| `ielts://task-types` | 阅读、写作、听力、口语格式 |
| `ielts://writing-criteria` | 任务完成度、CC、LR、GRA 标准 |
## 🎯 可用提示
| 提示 | 描述 |
|---|---|
| `ielts_tutor` | 针对特定评分目标的雅思辅导员 |
| `essay_feedback` | 详细的写作任务 1/2 反馈 |
| `question_generator` | 从段落中生成问题 |
---
## 📁 项目结构
```
ielts-mcp-server/
├── src/
│ └── ielts_mcp/
│ ├── server.py # FastMCP 实例 + 入口点
│ ├── config.py # Pydantic 设置来自 .env
│ ├── tools/
│ │ ├── gdrive_tools.py # Google Drive 工具（OAuth）
│ │ ├── document_tools.py # 本地文件工具
│ │ └── analysis_tools.py # AI 工具（Azure OpenAI）
│ ├── resources/
│ │ └── __init__.py # ielts:// URI 资源
│ └── prompts/
│ └── __init__.py # 可重复使用的提示模板
├── tests/
│ └── test_tools.py
├── .env.example
├── pyproject.toml
└── README.md
```
---
## ➕ 添加新工具
```python
# 1. 在 src/ielts_mcp/tools/my_tools.py 中创建函数
async def my_tool(param: str) -> dict:
"""显示给 Claude 的描述。"""
return {"result": param}
# 2. 在 src/ielts_mcp/tools/__init__.py 中注册
from .my_tools import my_tool
def register_tools(mcp: FastMCP) -> None:
...
mcp.tool()(my_tool) # 添加此行
```
---
## 🧪 运行测试
```bash
uv run pytest -v
```
---
## 🪟 Windows 快速启动脚本
在项目根目录创建 `start-mcp.bat`：
```batch
@echo off
uv --directory D:\python\tung_mcp run ielts-mcp --stdio
```
双击启动服务器，无需手动打开 VS Code 或激活虚拟环境。
---
## 🔒 安全注意事项
- `credentials.json` 和 `token.json` 存储在 `~/.ielts_mcp/` 中，**永远不会提交到 git**
- 服务器请求 **只读** Drive 范围 (`drive.readonly`) — 它无法修改您的文件
- OAuth 令牌自动刷新并仅本地存储
- 将 `credentials.json` 和 `token.json` 添加到 `.gitignore`
```gitignore
.env
.venv/
__pycache__/
*.pyc
*.egg-info/
```
---
## 📄 License
MIT License — 见 [LICENSE](LICENSE) 了解详情。
---
<div align="center">
使用 <a href="https://gofastmcp.com">FastMCP</a> 构建 · 由 <a href="https://docs.astral.sh/uv/">uv</a> 管理 · 由 <a href="https://claude.ai">Claude</a> 提供支持
</div>
