📚 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 — fast Python package manager
• Claude Desktop
• Google account with Drive access
• Google Cloud project with Drive API enabled

---

🚀 Installation

1. Install uv

# 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

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

cp .env.example .env

Edit .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
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

# 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:

{
  "mcpServers": {
    "ielts-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ielts-mcp-server",
        "run",
        "ielts-mcp",
        "--stdio"
      ]
    }
  }
}

Windows example:

{
  "mcpServers": {
    "ielts-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "D:/python/tung_mcp",
        "run",
        "ielts-mcp",
        "--stdio"
      ]
    }
  }
}

macOS example:

{
  "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

# 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

uv run pytest -v

---

🪟 Windows Quick Start Script

Create start-mcp.bat in the project root:

@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

.env
.venv/
__pycache__/
*.pyc
*.egg-info/

---

📄 License

MIT License — see 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>