# LingQ Progress MCP for ChatGPT

A tiny **read-only** MCP server that lets ChatGPT inspect your LingQ progress without receiving your LingQ password.

## What it exposes

- `list_languages` — active LingQ languages and the data LingQ returns for them (including known-word totals when available).
- `inspect_progress_capabilities` — asks LingQ which progress intervals/metrics are currently available.
- `get_progress_summary` — aggregate progress for a period.
- `get_progress_chart` — time-series data for a specific metric and period.

The server only performs HTTP `GET` requests to LingQ.

## 1. Requirements

- Node.js 18 or newer
- A LingQ account
- Your LingQ API key

Get your LingQ API key while logged in:

https://www.lingq.com/en/accounts/apikey/

**Do not send the key to anyone.** Keep it in the local `.env` file.

## 2. Configure

Open a terminal in this folder and run:

```bash
npm install
```

Copy `.env.example` to `.env`.

Windows PowerShell:

```powershell
Copy-Item .env.example .env
notepad .env
```

Put your key after `LINGQ_API_KEY=` and save.

## 3. Run locally

```bash
npm start
```

You should see:

```text
LingQ Progress MCP listening on http://localhost:8787/mcp
```

Opening `http://localhost:8787/` in a browser should show a simple health message.

## 4. Test with MCP Inspector (recommended)

In a second terminal:

```bash
npx @modelcontextprotocol/inspector@latest
```

Choose **Streamable HTTP** and connect to:

```text
http://localhost:8787/mcp
```

Call `list_languages` first. If it returns your LingQ languages, the key and LingQ API are working.

## 5. Make it reachable by ChatGPT

For a quick local test, expose port 8787 through an HTTPS tunnel such as ngrok:

```bash
ngrok http 8787
```

It will give you an HTTPS address. Add `/mcp` to the end, for example:

```text
https://example.ngrok.app/mcp
```

In ChatGPT, enable **Developer mode**, create/add a custom plugin/MCP connection, and paste that HTTPS `/mcp` URL.

Then you can ask things like:

- "Como tá meu russo no LingQ essa semana?"
- "Quantas palavras conhecidas eu tenho em russo e japonês?"
- "Compara meu progresso dos últimos 7 e 30 dias."
- "Quanto tempo eu ouvi neste mês?"
- "Mostra quais dias eu mais li esta semana."

## Security notes

- The LingQ API key stays on the computer/server running this project.
- The MCP responses never intentionally include the API key.
- All LingQ calls in this project are `GET` requests only.
- Do not commit `.env` to Git; it is already included in `.gitignore`.

## LingQ API caveat

LingQ's public API documentation is incomplete/outdated. The project therefore includes `inspect_progress_capabilities`, which asks the live LingQ progress endpoint what it currently supports instead of assuming every metric name forever.