LinguaMCP

Open curriculum protocol for AI language tutors — learn naturally through daily practice with any AI tool.

What is it?

LinguaMCP is an MCP (Model Context Protocol) server that serves daily language lessons from a structured curriculum. It works with Claude, Cursor, Windsurf, or any AI tool that supports MCP.

Instead of flashcards or grammar drills, you practice naturally through conversation. Your AI tutor knows what you've learned, tracks your progress, and introduces new material when you're ready.

Quick Start

Option 1: Zero-config SQLite (recommended)

# Install globally
npm install -g @lingua/mcp

# Initialize database with curriculum
lingua-mcp-init

# Start the server
lingua-mcp

That's it. No database to set up, no API keys, no cloud services. Your progress lives in ~/.lingua-mcp/lingua.db.

Option 2: Supabase (cloud or self-hosted)

# Clone and install
git clone https://github.com/Marsmanleo/LinguaMCP.git
cd LinguaMCP
npm install

# Set up environment
cp .env.example .env
# Edit .env with your Supabase credentials

# Run the Supabase migration (in supabase/migrations/)
# Then ingest the curriculum
npm run ingest

# Start the server
npm start

Configure Your AI Tool

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "lingua": {
      "command": "npx",
      "args": ["-y", "@lingua/mcp"]
    }
  }
}

Cursor / Windsurf

Add to your MCP settings:

{
  "lingua": {
    "command": "node",
    "args": ["/path/to/LinguaMCP/server.mjs"]
  }
}

Supabase mode

Set environment variables before starting:

SUPABASE_BASE_URL=https://your-project.supabase.co \
SUPABASE_ANON_KEY=your-anon-key \
node server.mjs

MCP Tools

Once connected, your AI tool gets three new tools:

Tool	Description
get_today_lesson	Returns your next unmastered lesson with context and practice prompts
get_user_progress	Shows mastery, practiced, and remaining counts
log_response	Records your practice response (score 1-5, ≥4 = mastered)

Curriculum

Currently using structured content from English-level-up-tips (50k+ stars, MIT License).

Available skill books:

• 🔗 Linking Words — 4 chapters, 20 lessons covering contrast, addition, cause-effect, and condition connectors

More skill books and languages coming soon.

How It Works

┌─────────────┐     MCP      ┌─────────────┐     Query     ┌──────────┐
│  Your AI    │──────────────▶│  LinguaMCP  │──────────────▶│ Database │
│  Tool       │◀──────────────│  Server     │◀──────────────│          │
└─────────────┘   Lessons &   └─────────────┘   Progress &   └──────────┘
                  Progress                      Lessons

1. You chat with your AI tool normally
2. The AI calls LinguaMCP to get your lesson for the day
3. You practice through conversation
4. LinguaMCP tracks what you've mastered and what's next

Architecture

server.mjs              ← MCP server entry point
storage/
  interface.mjs         ← Storage contract
  supabase.mjs          ← Supabase/PostgREST adapter
  sqlite.mjs            ← SQLite adapter (zero-config)
schema/
  sqlite.sql            ← SQLite schema
scripts/
  ingest-english-tips.ts  ← Content ingestion (Supabase)
  init-sqlite.mjs         ← Content ingestion (SQLite)
src/
  index.ts              ← TypeScript types

Storage Modes

Mode	When	Database	Best for
SQLite	No SUPABASE_BASE_URL set	~/.lingua-mcp/lingua.db	Personal use, self-hosted
Supabase	SUPABASE_BASE_URL is set	PostgreSQL via PostgREST	Cloud, multi-user, teams

Same tools, same responses, same curriculum. The server auto-detects which mode to use.

Contributing

See CONTRIBUTING.md for how to add curriculum content, storage adapters, or language support.

License

Apache License 2.0 — see LICENSE.

Curriculum content from English-level-up-tips is MIT licensed.

Related

• MarsNMe — AI memory companion (sister project)
• Model Context Protocol — The protocol that makes this work