# 📚 IELTS MCP Server

<div align="center">

![FastMCP](https://img.shields.io/badge/FastMCP-3.4.2-blue?style=flat-square)
![Python](https://img.shields.io/badge/Python-3.11+-green?style=flat-square)
![uv](https://img.shields.io/badge/uv-package%20manager-DE5FE9?style=flat-square)
![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=flat-square)

**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>