IELTS MCP Server
Allows reading the content of Google Docs files stored in Google Drive.
Provides direct, read-only access to Google Drive files, enabling listing, searching, and reading of documents (PDF, DOCX, Google Docs, Google Sheets, TXT) from a specified Drive folder.
Allows reading data from Google Sheets files stored in Google Drive.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@IELTS MCP Server search for Writing Task 1 sample answers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π IELTS MCP Server
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
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 syncThat'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 .envEdit .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
Go to Google Cloud Console
Create a new project
Navigate to APIs & Services β Library
Search for Google Drive API β click Enable
Step 2 β Create OAuth credentials
Go to APIs & Services β Credentials
Click + Create Credentials β OAuth 2.0 Client ID
Application type: Desktop app
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.jsonStep 4 β Add yourself as a test user
Go to APIs & Services β OAuth consent screen β Audience
Scroll to Test users β Add users
Enter your Gmail address β Save
βοΈ Claude Desktop Configuration
Find the config file:
OS | Path |
Windows |
|
macOS |
|
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 onExample prompts
Browse your Drive:
List all files in my IELTS Drive folderRead a document:
Read Cambridge 20.pdf and summarize the reading passagesGenerate practice questions:
Read IELTS Band 9 Vocab Secrets.pdf and create 10 flashcardsGet writing feedback:
Read cause_solution_task2.docx and analyze it against IELTS writing criteriaSearch your materials:
Find all files related to Writing Task 2 in my Driveπ οΈ Available Tools
Tool | Description |
| Search files across Drive by keyword |
| List all files inside a specific folder |
| Read content of a PDF, DOCX, or Google Doc |
| Search files by filename |
| List local files (requires |
| Read local PDF, DOCX, or TXT |
| Search local files by name |
| Estimate IELTS band level of a text (needs Azure OpenAI) |
| Generate IELTS-style questions from a passage (needs Azure OpenAI) |
| Extract key IELTS vocabulary with definitions (needs Azure OpenAI) |
π Available Resources
URI | Description |
| Band 1β9 descriptors |
| Reading, Writing, Listening, Speaking formats |
| Task Achievement, CC, LR, GRA criteria |
π― Available Prompts
Prompt | Description |
| IELTS tutor persona for a target band score |
| Detailed Writing Task 1/2 feedback |
| 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 --stdioDouble-click to start the server without opening VS Code or activating a venv manually.
π Security Notes
credentials.jsonandtoken.jsonare stored in~/.ielts_mcp/and never committed to gitThe server requests read-only Drive scope (
drive.readonly) β it cannot modify your filesOAuth tokens auto-refresh and are stored locally only
Add
credentials.jsonandtoken.jsonto.gitignore
.env
.venv/
__pycache__/
*.pyc
*.egg-info/π License
MIT License β see LICENSE for details.
Available Tools
10 toolsanalyze_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
gdrive_searchA
TΓ¬m kiαΊΏm file IELTS trΓͺn Drive theo tΓͺn.
Inputs: query (required), max_results. 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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Give Claude only the Google Drive files you choose. Every action logged.
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects Claude to Google Docs, allowing users to list, read, create, update, search, and delete documents in their Google Drive through natural language interactions.1MIT
- AlicenseNot gradedqualityDmaintenanceConnects Claude Desktop to Google Drive, allowing Claude to access and interact with your Drive files and folders securely through OAuth authentication.1ISC
- FlicenseNot gradedqualityNot gradedmaintenanceConnects AI assistants like Claude to Google Drive, enabling them to browse, read, search, create, and edit files and folders using Google's official API with secure authentication.-
- AlicenseNot gradedqualityDmaintenanceConnects Claude Desktop to Google Docs and Google Drive, enabling comprehensive document reading, writing, formatting, structuring, and complete Drive file management including shared drives support through OAuth 2.0 authentication.10 npm3MIT