{
"markdown": "# PlainQuery\n\n**Ask your database questions in plain English.** PlainQuery connects PostgreSQL databases to Claude, Cursor, or VS Code — and answers with real, structured data instead of guesses.\n\n[](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Jarvis-27/mcp-db-agent)\n[](https://github.com/Jarvis-27/mcp-db-agent/actions/workflows/ci.yml)\n\n\n
\n \n
\n\n---\n\n## What it does\n\nYou connect a database once. Then, from any MCP client, you ask questions like:\n\n> _\"How many orders did we ship in March?\"_\n> _\"Which 5 customers spent the most last year?\"_\n> _\"What's the average order value by month?\"_\n\nPlainQuery introspects your schema, generates SQL with an LLM, **validates it for safety**, runs it, and returns structured JSON. If a query fails, it reads the error and **retries automatically**.\n\n## Why PlainQuery\n\n- **Natural language, real answers** — no SQL required; results come from your actual data, not a hallucination.\n- **Read-only and safe by design** — every query is checked before it runs: writes (`INSERT`/`UPDATE`/`DELETE`/DDL) are blocked, dangerous functions and patterns are scanned out, and a `LIMIT` is injected automatically.\n- **Self-correcting** — when a generated query errors, the agent feeds the error back to the LLM and retries (up to a configurable limit).\n- **Schema-aware** — automatically introspects and caches your schema, so questions map to the right tables and columns.\n- **Works with any MCP client** — Claude Desktop, Cursor, VS Code Copilot, or anything that speaks MCP.\n- **Secure multi-tenant hosting** — database URLs and LLM keys are Fernet-encrypted at rest; user-supplied connection strings are SSRF-guarded; every request is tenant-scoped.\n- **Hosted or self-hosted** — use the managed service, or run the whole stack yourself with Docker.\n- **Bring your own LLM** — Anthropic Claude or Groq.\n\n## How it works\n\n```\nYour question\n → Schema introspection (reads tables/columns, cached)\n → SQL generation (schema + question → LLM → SQL)\n → Safety validation (blocks writes, scans dangerous patterns, injects LIMIT)\n → Execution (runs read-only, with a timeout)\n → Self-correction retry (on error: feed it back to the LLM, fix, re-run)\n → Structured JSON result\n```\n\n### Architecture\n\n
\n \n
\n\n---\n\n## Quick start\n\n### Option 1 — Use the hosted service (no install)\n\n1. Sign up at **`https://plainquery.in`** and verify your email.\n2. Connect your PostgreSQL database and create an API key.\n3. Add the server to your MCP client (see [Connect your MCP client](#connect-your-mcp-client)).\n\nThat's it — start asking questions.\n\n### Option 2 — Run it yourself\n\nSee [Self-hosting & local development](#self-hosting--local-development) below.\n\n## Connect your MCP client\n\nPlainQuery is published on the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Jarvis-27/mcp-db-agent) as `io.github.Jarvis-27/mcp-db-agent`, so registry-aware clients can discover it directly.\n\nTo configure a client manually, point it at the MCP endpoint and pass your API key:\n\n```json\n{\n \"mcpServers\": {\n \"plainquery\": {\n \"url\": \"https://plainquery.in/mcp\",\n \"headers\": { \"X-API-Key\": \"mdbk_your_key_here\" }\n }\n }\n}\n```\n\nThe backend can also generate ready-to-paste config for VS Code, Cursor, and generic HTTP clients — call `POST /api/v1/account/setup-payloads` (see [Setup payloads](#setup-payloads)). MCP clients can authenticate with an OAuth 2.1 bearer token or an API key, depending on `MCP_AUTH_MODE`.\n\n---\n\n## Self-hosting & local development\n\n### Prerequisites\n\n- Python 3.12+\n- `uv`\n- Node.js 20+ and `pnpm` for the frontend\n- At least one LLM API key (`ANTHROPIC_API_KEY` or `GROQ_API_KEY`)\n\n### Backend\n\n```bash\nuv sync\ncp .env.example .env\n```\n\nEdit `.env` with at least:\n\n- `CREDENTIAL_ENCRYPTION_KEYS`\n- `REGISTRATION_OPEN=true`\n- one LLM provider key plus `LLM_PROVIDER`\n\nRun the backend:\n\n```bash\nuv run uvicorn src.app:app --reload --host 0.0.0.0 --port 8000\n```\n\nThe backend mounts:\n\n- REST API at `http://localhost:8000/api`\n- MCP endpoint at `http://localhost:8000/mcp`\n\n### Frontend\n\n```bash\ncd frontend\npnpm install\npnpm dev\n```\n\nOpen `http://localhost:3000`, sign up, complete setup, link your OAuth identity via account settings, then connect an MCP client at `http://localhost:8000/mcp`. The client will complete the OAuth flow automatically, or you can use an API key in `api_key_only` / `hybrid` mode.\n\n### Runtime model\n\n- Backend API: FastAPI/Starlette at `src.app:app`\n- Frontend: Next.js app in `frontend/`\n- Auth: passwordless email verification and login links\n- MCP auth: OAuth 2.1 bearer tokens (`oauth_only`), API keys (`api_key_only`), or both (`hybrid`) — set via `MCP_AUTH_MODE`\n- Setup payloads: `POST /api/v1/account/setup-payloads`\n- Billing: Stripe Checkout, Customer Portal, and webhook-confirmed Free/Pro entitlements\n\nThe product model is single-account and user-scoped:\n`signup → verify email → connect database → link OAuth identity → use /mcp → upgrade with Stripe`\n\n## Security\n\n
![\"PlainQuery](\"docs/PlainQuery_GIF.gif\")
\n![\"PlainQuery](\"docs/diagram/plainquery-architecture.png\")
\n![\"PlainQuery](\"docs/diagram/plainquery-security.png\")
\n