Skip to main content
Glama

πŸ“š IELTS MCP Server

FastMCP Python uv License Platform

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.


✨ 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


Related MCP server: Google Drive MCP

πŸ—οΈ 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.


Available Tools

10 tools
analyze_textB

Analyze a text passage for IELTS band level and key features.

Inputs: text (required). Returns: object

extract_vocabularyA

Extract IELTS-relevant vocabulary with definitions and examples.

Inputs: text (required), count, min_band. Returns: object

gdrive_list_filesB

Liệt kΓͺ file/folder trΓͺn Google Drive theo tα»« khΓ³a tΓ¬m kiαΊΏm.

Inputs: query, folder_id, max_results. Returns: object

gdrive_list_folderA

Liệt kΓͺ tαΊ₯t cαΊ£ file bΓͺn trong mα»™t folder cα»₯ thể.

Inputs: folder_id (required). Returns: object

gdrive_read_fileA

Đọc nα»™i dung text cα»§a mα»™t file tα»« Google Drive.

Hα»— trợ: Google Docs, PDF, DOCX, TXT, Google Sheets (CSV), Slides.

Inputs: file_id (required). Returns: object

generate_questionsA

Generate IELTS-style practice questions from a passage.

Inputs: passage (required), count, question_type. Returns: object

list_documentsB

List IELTS documents and folders.

Inputs: folder. Returns: object

read_documentA

Read the text content of a document (PDF, DOCX, or TXT).

Inputs: path (required). Returns: object

search_documentsB

Search for documents by filename.

Inputs: query (required), max_results. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 10 tools

    Disambiguation2/5

    Multiple tools have overlapping purposes, especially around document access: gdrive_list_files and gdrive_search both search by name, search_documents also searches, and read_document vs gdrive_read_file differentiate only by source. This ambiguity makes it hard for an agent to choose the correct tool.

    Naming Consistency3/5

    All tool names use snake_case, but the gdrive_ prefix is applied inconsistently (e.g., gdrive_list_folder vs list_documents) and the verb/noun order varies (search_documents vs gdrive_search). The names are readable but the pattern is not uniform.

    Tool Count4/5

    The server has 10 tools, within the typical 3-15 range. However, the document management tools are redundant (multiple search/list functions), making the set feel slightly over-provisioned even though the count itself is reasonable.

    Completeness3/5

    The server covers document access and IELTS text analysis (band level, questions, vocabulary), but lacks tools for writing assessment, speaking, or listening practice. The absence of create/update/delete operations for documents is acceptable, but the broader IELTS domain is incomplete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers