Content
English Study Workflow
Claude Desktop + Google Sheets automated English expression learning workflow.
Just ask a question, Claude explains the meaning, nuance, and example sentences, and with a single phrase "** 정리해줘 **", it automatically saves to the appropriate Google Sheets.
> ✨ **No additional costs** beyond Claude subscription. Everything runs locally and within Google API free quotas.
## Architecture
```
┌──────────────────┐ ┌───────────────────────┐ ┌──────────────────┐
│ Claude Desktop │ ◀────▶ │ english-study-mcp │ ◀───▶ │ Google Sheets │
│ (Chat UI) │ MCP │ (Local Python Server) │ OAuth │ (5 Learning Sheets) │
└──────────────────┘ └───────────────────────┘ └──────────────────┘
▲ │
│ Project Instructions │ 8 tools:
│ + Sheet registry │ add/search/list/quiz/
│ │ correct/translate/update/review
```
## 5 Active Sheets
| Sheet | Purpose |
|---|---|
| **daily** | General English expressions, vocabulary, phrasal verbs, and idioms learning |
| **corrections** | Natural corrections of English sentences + pronunciation tips |
| **pronunciation** | Pronunciation and intonation tips |
| **assertions** | Unit-by-unit assertions and grounds for exams |
| **translation** | Video/audio translation practice (original vs. attempt vs. correct answer) |
## 8 MCP Tools
**Basic Tools (4)**
- `add_expression` — Add expressions to sheets (automatic column mapping)
- `search_expressions` — Search and check duplicates
- `list_sheets` — List sheets and structures
- `quiz_random` — Random samples for review quizzes
**Specialized Tools (4)**
- `correct_expression` — Dedicated to corrections sheet (my_version/corrected/reason in one go)
- `add_translation_row` — Dedicated to translation sheet (video translation practice)
- `update_expression` — Update existing rows and add example sentences
- `weekly_review` — Aggregate learning data by period (provided by Claude)
## Quick Start
### Requirements
- Python 3.10+
- Claude Desktop ([download](https://claude.ai/download))
- Google account
### 1. Installation
```bash
git clone https://github.com/<your-username>/english-study-workflow.git
cd english-study-workflow
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
cd mcp-server
pip install -e .
```
### 2. Google Cloud Setup
Detailed guide: [`docs/01-google-cloud-setup.md`](docs/01-google-cloud-setup.md)
Summary:
1. Create a new project in Google Cloud Console
2. Enable Sheets API and Drive API
3. Issue OAuth 2.0 client ID (desktop app) → `credentials.json`
4. Move to `~/.config/english-study-mcp/credentials.json`
### 3. Initial Authentication
```bash
python -m english_study_mcp.auth
```
Open browser, Google login → "Advanced" → "Proceed (not secure)" → grant permissions. `token.json` is automatically saved.
### 4. Prepare Google Sheets
Upload reconstructed Excel file to Google Drive → convert to Google Sheets.
Or create 5 tabs directly in an empty sheet. Details: [`docs/04-sheet-schema.md`](docs/04-sheet-schema.md)
### 5. Set up Sheet Registry
```bash
cp config/sheets_registry.example.yaml config/sheets_registry.yaml
```
Enter your Sheets ID in `spreadsheet_id`.
### 6. Connect Claude Desktop
Refer to `config/claude_desktop_config.example.json` and add MCP server to Claude Desktop settings:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Details: [`docs/03-claude-desktop-config.md`](docs/03-claude-desktop-config.md)
### 7. Create Project
New Project in Claude Desktop → Instructions → paste [`prompts/project-instructions.md`](prompts/project-instructions.md).
## Usage Examples
```
Me: "What does 'pick someone's brain' mean?"
Claude: [explains meaning, nuance, and 3 example sentences]
Me: " 정리해줘 in daily"
Claude: [checks duplicates with search_expressions → adds to daily sheet]
✅ Added to daily sheet at row 111.
```
More examples: [`docs/05-usage-examples.md`](docs/05-usage-examples.md) — includes scenarios for combining 5 sheets × 8 tools.
## Repository Structure
```
english-study-workflow/
├── README.md, LICENSE, .gitignore
├── docs/ # setup and usage guides for steps 1-6
├── prompts/ # Project Instructions, prompt templates
├── config/ # *.example.* (your values are local only)
└── mcp-server/ # custom MCP server
├── pyproject.toml
└── src/english_study_mcp/
├── server.py # entry point, 8 tools registered
├── auth.py # OAuth initial authentication
├── sheets_client.py # gspread wrapper
├── schemas/registry.py # YAML schema loader
└── tools/ # implementation of 8 tools
├── add_expression.py
├── search_expressions.py
├── list_sheets.py
├── quiz_random.py
├── correct_expression.py
├── add_translation_row.py
├── update_expression.py
└── weekly_review.py
```
## Secret Management (public repo precautions)
`.gitignore` includes the following to prevent pushing:
- `credentials.json` / `token.json` — OAuth secrets
- `config/sheets_registry.yaml` — your sheet ID
- `.env`
Keep your config files in `~/.config/english-study-mcp/` or locally.
## Customization
- **Add new tools**: add a file to `mcp-server/src/english_study_mcp/tools/` and register in `server.py`
- **Change sheet schema**: modify `config/sheets_registry.yaml` (no code changes needed)
- **Adjust prompts**: modify `prompts/project-instructions.md`
## License
MIT License. Feel free to fork and use.
## Acknowledgments
- [Anthropic Claude](https://www.anthropic.com/) + [Model Context Protocol](https://modelcontextprotocol.io/)
- [gspread](https://github.com/burnash/gspread) — Google Sheets Python library
