README.md•2 kB
# Read-only Database MCP
Minimal TeamSpeak/TypeScript setup that exposes a read-only database Model Context Protocol server and a small UI for managing DB configs, toggling light/dark mode, and viewing usage history.
## Prerequisites
- Node 18+
- A PostgreSQL or MySQL/MariaDB database user with read-only permissions
## Install
```bash
npm install
```
## Run the UI + API
Serves the config/history API and the minimalist UI at `http://localhost:4000`.
```bash
npm run dev
```
## Run the MCP server
The MCP server reads the same saved configs from `data/state.json` and only exposes read-only tools.
```bash
npm run mcp
```
Tools exposed (over stdio):
- `list_tables` — input `{ db: "<configName>" }`
- `preview_table` — input `{ db: "<configName>", table: "table_name", limit?: number }`
- `run_select` — input `{ db: "<configName>", sql: "SELECT ..." }` (rejects non-SELECT)
Use these tool names when connecting your model/agent to the MCP server.
## How to use
1) Start `npm run dev` and open the UI. Enter DB connection details and click **Save config**. Set SSL mode to `disable`, `require`, or `no-verify` (self-signed).
- For MySQL/MariaDB TCP/IP, pick type “MySQL / MariaDB”.
2) Select the saved config in “Use config” to list tables, preview a table, or run a SELECT.
3) Each successful MCP/HTTP call records a history entry (DB name, tables touched, timestamp).
4) In your agent, connect to the MCP server via stdio and call the tools using the saved `db` name; you only need to pass the friendly name, not the credentials.
## Notes
- Configs and history live in `data/state.json`. Delete that file to reset.
- The server enforces read-only mode with `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY` and rejects non-SELECT queries.
- If your MCP SDK exports different helper names, adjust `src/mcp-server.ts` registration to match your SDK version.
- Extend `src/db.ts` to add other engines (MySQL, SQLite) while keeping read-only guards.