sqlite-readonly-mcp

A read-only SQLite Model Context Protocol service running on remote Linux, using Streamable HTTP (/mcp), authenticated via Bearer Token, and returning query results as JSON text. Designed to be placed behind Nginx (HTTPS), with the upstream listening only on localhost.

Features

• Tool sqlite_query: Single SELECT / WITH / EXPLAIN statement, returns JSON with { rows, rowCount }.

• Tool list_tables: Lists non-system table names.

• SQLite: better-sqlite3 readonly + fileMustExist; application-level restrictions on single statements and query prefixes.

• GET /health: For loopback access only, used for probes (see src/server.ts).

• Transport: Streamable HTTP (/mcp) + legacy SSE (GET /sse, POST /messages), for easy fallback by Cursor when needed.

Related MCP server: PostgreSQL MCP Server

Environment Variables

Local Build and Run

npm install
npm run build
export SQLITE_PATH=/path/to/db.sqlite
export BEARER_TOKEN='your-secret-token'
export ALLOWED_HOSTS='127.0.0.1,localhost'
node dist/server.js

Development and debugging: npm run dev

Nginx and systemd

See deploy/nginx.example.conf, deploy/sqlite-readonly-mcp.service, and deploy/sqlite-readonly-mcp.env.example.

Key points: Pass Authorization, Accept, Content-Type, and mcp-session-id to the upstream; disable proxy_buffering for SSE/chunked responses. The examples include **/sse** and **/messages** (legacy SSE fallback), reverse-proxied alongside Streamable HTTP's /mcp.

Running as root (Recommended Example)

To simplify read permission configuration for the SQLite file and parent directory, the example uses root to start the service (the systemd unit does not set User= / Group=, defaulting to root).

1. Place the code and build artifacts in, for example, /opt/sqlite-readonly-mcp, and run npm ci --omit=dev and npm run build.

2. Copy the environment file and fill in the variables:

 sudo cp deploy/sqlite-readonly-mcp.env.example /etc/sqlite-readonly-mcp.env
 sudo chmod 600 /etc/sqlite-readonly-mcp.env

3. Install and enable the unit (modify WorkingDirectory and the absolute path to node in ExecStart as needed):

 sudo cp deploy/sqlite-readonly-mcp.service /etc/systemd/system/
 sudo systemctl daemon-reload
 sudo systemctl enable --now sqlite-readonly-mcp
 sudo systemctl status sqlite-readonly-mcp

If you previously added User=mcp yourself, remove that line before running daemon-reload and restart.

Security Note: A compromised root process has a larger impact; please ensure you use HTTPS, Bearer tokens, localhost listening + Nginx, and a firewall. If minimal privileges are required, revert to a dedicated user and configure data file and path permissions separately.

Manual Verification (curl)

MCP requires clients to accept both application/json and text/event-stream:

curl -sS -D - \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \
  "https://mcp.example.com/mcp"

An incorrect token should return 401.

Cursor Client

In Cursor's MCP settings, configure the HTTPS URL for this remote service (e.g., https://mcp.example.com/mcp). If Bearer is required, check if your current Cursor version supports configuring custom headers for remote MCP; if not, you will need to add a gateway layer locally that includes the fixed Authorization header (see risk documentation).

Operations

See docs/RUNBOOK.md for details.

License

MIT (consistent with @modelcontextprotocol/sdk; subject to individual dependency licenses).