Content
# 📚 IELTS MCP Server
<div align="center">
**A FastMCP server that connects Claude Desktop directly to your Google Drive IELTS study materials.**
Read PDFs, DOCX files, and Google Docs — without downloading anything to your local machine.
</div>
---
## ✨ Features
- 🔗 **Direct Google Drive access** — connect to your Drive folder without downloading files
- 📄 **Multi-format support** — PDF, DOCX, Google Docs, Google Sheets, TXT
- 🔍 **Smart search** — find documents by filename across your entire Drive
- 📁 **Folder navigation** — browse nested folder structures
- 🤖 **AI-powered analysis** — generate IELTS practice questions and extract vocabulary *(requires Azure OpenAI)*
- 📖 **Built-in IELTS resources** — band descriptors, task formats, writing criteria
- 🎯 **Reusable prompts** — IELTS tutor, essay feedback, question generator
---
## 🏗️ Architecture
```
Claude Desktop
│ stdio (JSON-RPC 2.0)
▼
┌─────────────────────────────────┐
│ FastMCP Server │
│ │
│ ┌─────────┐ ┌──────────────┐ │
│ │ tools/ │ │ resources/ │ │
│ │ │ │ │ │
│ │ gdrive │ │ ielts:// │ │
│ │ local │ │ band-desc │ │
│ │ analyze │ │ task-types │ │
│ └────┬────┘ └──────────────┘ │
└───────┼─────────────────────────┘
│
┌────┴────────────────┐
│ │
▼ ▼
Google Drive Azure OpenAI
(OAuth 2.0) (optional)
```
---
## 📋 Prerequisites
- Python 3.11+
- [uv](https://docs.astral.sh/uv/) — fast Python package manager
- [Claude Desktop](https://claude.ai/download)
- Google account with Drive access
- Google Cloud project with Drive API enabled
---
## 🚀 Installation
### 1. Install 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. Clone and install
```bash
git clone https://github.com/your-username/ielts-mcp-server.git
cd ielts-mcp-server
uv sync
```
That's it — `uv sync` creates the virtual environment and installs all dependencies automatically. No manual `venv` or `pip install` needed.
### 3. Configure environment
```bash
cp .env.example .env
```
Edit `.env`:
```env
# Path to local IELTS documents (optional, if not using Google Drive)
DOCUMENTS_DIR=./documents
# Azure OpenAI (optional, for AI-powered tools)
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_KEY=your-key-here
AZURE_OPENAI_DEPLOYMENT=gpt-4o
```
---
## 🔑 Google Drive Setup
### Step 1 — Create a Google Cloud project
1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Create a new project
3. Navigate to **APIs & Services → Library**
4. Search for **Google Drive API** → click **Enable**
### Step 2 — Create OAuth credentials
1. Go to **APIs & Services → Credentials**
2. Click **+ Create Credentials → OAuth 2.0 Client ID**
3. Application type: **Desktop app**
4. Click **Create** → **Download JSON**
### Step 3 — Install credentials file
Rename the downloaded file to `credentials.json` and place it here:
```
# 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
```
### Step 4 — Add yourself as a test user
1. Go to **APIs & Services → OAuth consent screen → Audience**
2. Scroll to **Test users → Add users**
3. Enter your Gmail address → **Save**
---
## ⚙️ Claude Desktop Configuration
Find the config file:
| OS | Path |
|---|---|
| Windows | `%AppData%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
Add the `mcpServers` key:
```json
{
"mcpServers": {
"ielts-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/ielts-mcp-server",
"run",
"ielts-mcp",
"--stdio"
]
}
}
}
```
**Windows example:**
```json
{
"mcpServers": {
"ielts-mcp": {
"command": "uv",
"args": [
"--directory",
"D:/python/tung_mcp",
"run",
"ielts-mcp",
"--stdio"
]
}
}
}
```
**macOS example:**
```json
{
"mcpServers": {
"ielts-mcp": {
"command": "uv",
"args": [
"--directory",
"/Users/yourname/ielts-mcp-server",
"run",
"ielts-mcp",
"--stdio"
]
}
}
}
```
> **Why `uv run`?** It automatically uses the project's virtual environment — no need to find the exact path to the executable, and it works the same across all platforms.
Restart Claude Desktop — you should see the 🔨 tools icon in the chat input.
---
## 💬 Usage
### First-time authentication
On the first tool call, a browser window will open automatically:
```
Claude: "Let me list your IELTS files..."
→ Browser opens → Sign in with Google → Allow access
→ Token saved to ~/.ielts_mcp/token.json
→ Works automatically from now on
```
### Example prompts
**Browse your Drive:**
```
List all files in my IELTS Drive folder
```
**Read a document:**
```
Read Cambridge 20.pdf and summarize the reading passages
```
**Generate practice questions:**
```
Read IELTS Band 9 Vocab Secrets.pdf and create 10 flashcards
```
**Get writing feedback:**
```
Read cause_solution_task2.docx and analyze it against IELTS writing criteria
```
**Search your materials:**
```
Find all files related to Writing Task 2 in my Drive
```
---
## 🛠️ Available Tools
| Tool | Description |
|---|---|
| `gdrive_list_files` | Search files across Drive by keyword |
| `gdrive_list_folder` | List all files inside a specific folder |
| `gdrive_read_file` | Read content of a PDF, DOCX, or Google Doc |
| `gdrive_search` | Search files by filename |
| `list_documents` | List local files (requires `DOCUMENTS_DIR`) |
| `read_document` | Read local PDF, DOCX, or TXT |
| `search_documents` | Search local files by name |
| `analyze_text` | Estimate IELTS band level of a text *(needs Azure OpenAI)* |
| `generate_questions` | Generate IELTS-style questions from a passage *(needs Azure OpenAI)* |
| `extract_vocabulary` | Extract key IELTS vocabulary with definitions *(needs Azure OpenAI)* |
## 📖 Available Resources
| URI | Description |
|---|---|
| `ielts://band-descriptors` | Band 1–9 descriptors |
| `ielts://task-types` | Reading, Writing, Listening, Speaking formats |
| `ielts://writing-criteria` | Task Achievement, CC, LR, GRA criteria |
## 🎯 Available Prompts
| Prompt | Description |
|---|---|
| `ielts_tutor` | IELTS tutor persona for a target band score |
| `essay_feedback` | Detailed Writing Task 1/2 feedback |
| `question_generator` | Generate questions from a passage |
---
## 📁 Project Structure
```
ielts-mcp-server/
├── src/
│ └── ielts_mcp/
│ ├── server.py # FastMCP instance + entry point
│ ├── config.py # Pydantic settings from .env
│ ├── tools/
│ │ ├── gdrive_tools.py # Google Drive tools (OAuth)
│ │ ├── document_tools.py # Local file tools
│ │ └── analysis_tools.py # AI tools (Azure OpenAI)
│ ├── resources/
│ │ └── __init__.py # ielts:// URI resources
│ └── prompts/
│ └── __init__.py # Reusable prompt templates
├── tests/
│ └── test_tools.py
├── .env.example
├── pyproject.toml
└── README.md
```
---
## ➕ Adding a New Tool
```python
# 1. Create the function in src/ielts_mcp/tools/my_tools.py
async def my_tool(param: str) -> dict:
"""Description shown to Claude."""
return {"result": param}
# 2. Register in src/ielts_mcp/tools/__init__.py
from .my_tools import my_tool
def register_tools(mcp: FastMCP) -> None:
...
mcp.tool()(my_tool) # add this line
```
---
## 🧪 Running Tests
```bash
uv run pytest -v
```
---
## 🪟 Windows Quick Start Script
Create `start-mcp.bat` in the project root:
```batch
@echo off
uv --directory D:\python\tung_mcp run ielts-mcp --stdio
```
Double-click to start the server without opening VS Code or activating a venv manually.
---
## 🔒 Security Notes
- `credentials.json` and `token.json` are stored in `~/.ielts_mcp/` and **never committed to git**
- The server requests **read-only** Drive scope (`drive.readonly`) — it cannot modify your files
- OAuth tokens auto-refresh and are stored locally only
- Add `credentials.json` and `token.json` to `.gitignore`
```gitignore
.env
.venv/
__pycache__/
*.pyc
*.egg-info/
```
---
## 📄 License
MIT License — see [LICENSE](LICENSE) for details.
---
<div align="center">
Built with <a href="https://gofastmcp.com">FastMCP</a> · Managed by <a href="https://docs.astral.sh/uv/">uv</a> · Powered by <a href="https://claude.ai">Claude</a>
</div>
