sqlnow-mcp

# sqlnow-mcp An MCP server for DuckDB with an interactive table viewer. Point it at a data directory, attach files or external databases, and explore data through an LLM host such as Cursor or Claude Desktop. Query results from `run_query`, `sample_table`, and `value_counts` render as a scrollable grid inside the host via [MCP Apps](https://modelcontextprotocol.io/). Use `run_query_json` for small SELECT results the model needs as JSON (aggregations, counts, spot checks) — not for large exports. ## Requirements - Python 3.11+ - [uv](https://docs.astral.sh/uv/) (recommended) or pip - Node.js 18+ (only if you need to rebuild the table UI) ## Install From a clone of this repo: ```bash uv sync ``` Or run without installing globally: ```bash uvx sqlnow-mcp --mode local --data-dir ~/mydata ``` ## MCP server Two modes are available: - **local** — read/write; point at a data directory, switch databases, attach files and external connections. - **publish** — read-only; single database with curated `metadata.yaml` (and optional `stats.json`) for sharing a branded dataset. Transport (`stdio`, HTTP) works the same in both modes. ### Local mode ```bash sqlnow-mcp --mode local --data-dir ~/mydata ``` `--data-dir` is the working directory for `.db` files and attachable data. Session state (active database, attached sources) persists for the lifetime of the server process. ### Publish mode ```bash sqlnow-mcp --mode publish \ --db ~/datasets/gemlive.db \ --metadata ~/datasets/metadata.yaml \ --stats ~/datasets/stats.json ``` `--stats` is optional. The server name and instructions come from metadata (`short_name`, `welcome`, `example_questions`, etc.). Queries are SELECT-only with a default 10s timeout, 50% memory limit, and 1 DuckDB thread (all overridable). **stdio (Claude Desktop):** ```json { "mcpServers": { "gem-data": { "command": "uvx", "args": [ "sqlnow-mcp", "--mode", "publish", "--db", "/path/to/gemlive.db", …