Content
# db-lens-mcp
Default Language: English
English version: [README.en.md](README.en.md)
## Introduction
`db-lens-mcp` is a relational database context MCP tool for backend developers and AI programming tools.
It allows Codex, Claude Code, Trae, and other AI programming tools to safely read database table structures, indexes, capacity estimates, and SELECT execution plans, providing database layer context for writing code, modifying SQL, and troubleshooting potential slow queries.
It is not a universal SQL client, does not provide arbitrary SQL execution capabilities, and will not modify tables, create indexes, or modify data.
## Application Scenarios
You can understand `db-lens-mcp` as a "read-only database lens" for AI: AI does not need to log in to the database console or obtain a complete connection string to view database context through MCP.
It is mainly used for:
- Checking table structures: fields, types, primary keys, and comments.
- Checking indexes: index fields, uniqueness, order, type, and cardinality estimates.
- Viewing table size: row estimates, data capacity, and index capacity.
- Analyzing `SELECT`: viewing execution plans, prompting full table scans, index misses, and high scan row counts.
- Assisting AI in writing backend code: before modifying DAO, Mapper, Repository, Service, or SQL, let AI understand the real database structure.
It is not used for:
- Using it as a database management tool or SQL console.
- Letting AI automatically execute `INSERT`, `UPDATE`, `DELETE`, DDL, or maintenance operations.
- Replacing DBA's complete slow query diagnosis, capacity planning, or index design review.
- As a complete team HTTP/SSE service in the first version; server deployment currently only reserves basic functionality.
## Installation
Execute a command:
```bash
curl -fsSL https://raw.githubusercontent.com/MagicPelican/db-lens-mcp/master/scripts/install.sh | sh
```
After installation, follow the next steps as prompted by the terminal output. Normally, first check the installation:
```bash
db-lens doctor
```
View available commands:
```bash
db-lens help
```
## Configuration Process
Only three steps are required.
### 1. Add Database
```bash
db-lens config add
```
Enter the following information as prompted:
- Profile name, e.g., `local-dev`
- Database address and port
- Database name, multiple databases separated by English commas
- Username and password
It is recommended to use a read-only database account.
### 2. Test Connection
```bash
db-lens config test local-dev
```
### 3. Connect to AI Client
Codex:
```bash
db-lens mcp install-codex
```
Claude Code:
```bash
db-lens mcp install-claude-code
```
Trae:
```bash
db-lens mcp install-trae
```
After installing MCP configuration, restart the corresponding client, and then let AI use `db-lens` to view database context.
If the Agent or MCP client you are using does not directly support it:
```bash
db-lens mcp handoff
```
Send the entire output to the corresponding Agent, and let it add `db-lens` to its MCP configuration according to the prompt.
## Capabilities Available to AI
MCP tools only expose fixed whitelist capabilities:
| Tool | Effect |
| --- | --- |
| `list_profiles` | View configured connection profiles, no password returned |
| `list_databases` | View databases visible under the current profile |
| `refresh_table_cache` | Refresh table to database local mapping cache |
| `find_tables` | Find tables in the database by table name or keyword |
| `list_tables` | View table lists under the specified database |
| `describe_table` | View table fields, primary keys, and comments |
| `list_indexes` | View table indexes, uniqueness, field order, index type, and cardinality estimates |
| `get_table_stats` | View row estimates, data capacity, and index capacity |
| `explain_select` | Generate `EXPLAIN` internally for safe single `SELECT` execution tools |
| `inspect_query` | Return SQL-related table structure, index, statistics, execution plan, and basic risk prompts at once |
Commonly used methods include directly letting AI describe needs, such as:
```text
Please use db lens to check the orders table structure and indexes.
```
```text
Please use db lens to analyze whether this SQL may be slow:
select * from orders where user_id = ? order by created_at desc limit 20
```
## Security Boundary
The security design of `db-lens-mcp` focuses on "read-only context + whitelist tool".
- Do not expose universal SQL execution tools.
- Only allow analysis of single `SELECT`.
- User-written `EXPLAIN` will be rejected; `EXPLAIN` can only be generated internally by the tool.
- Multi-statement SQL will be rejected.
- `INSERT`, `UPDATE`, `DELETE`, DDL, `CALL`, `LOAD DATA`, transaction control, and other statements will be rejected.
- SQL verification is based on the current dialect's AST parsing, not just relying on string prefix judgment.
- SQL with placeholders but no provided parameters can return table structure and index context but will not fabricate parameters to execute `EXPLAIN`.
- Error information returned by MCP to AI will be desensitized for common passwords, keys, and connection strings.
- `config list` does not display passwords, ciphertext, or master keys.
## Common Commands
```bash
db-lens doctor
db-lens help
db-lens config add
db-lens config update local-dev
db-lens config delete old-profile
db-lens config list
db-lens config test local-dev
db-lens cache refresh local-dev
db-lens mcp install-codex
db-lens mcp install-claude-code
db-lens mcp install-trae
db-lens mcp handoff
db-lens mcp config --client codex
db-lens mcp config --client claude-code
db-lens mcp config --client trae
db-lens mcp config
db-lens mcp run
```
Description:
- `db-lens mcp run` is used to manually start the MCP stdio server, mainly for troubleshooting.
- `db-lens mcp config` only prints MCP configuration fragments and does not automatically write to the client configuration.
- `db-lens mcp install-*` will try to automatically write to the corresponding client configuration.
## Advanced Configuration
Generally, users do not need to write configuration files manually. When scripting, Docker, or server deployment is required, configuration files and environment variables can be used.
The current default configuration example uses the `mysql` driver, suitable for relational databases compatible with MySQL protocol/dialect. Other database dialects can be extended in subsequent versions.
Configuration file example:
```toml
[profiles.local-dev]
driver = "mysql"
host = "127.0.0.1"
port = 3306
databases = ["app_db", "audit_db"]
username = "readonly_user"
password = "enc:v1:..."
connect_timeout_seconds = 5
read_timeout_seconds = 10
```
Common environment variables:
```text
DB_LENS_CONFIG_FILE=/path/to/config.toml
DB_LENS_MASTER_KEY=...
```
Configuration priority:
```text
CLI parameter > environment variable > config.toml > default value
```
Interactive configuration commands support specifying languages:
```bash
db-lens config add --language zh
db-lens config add --language en
```
`config add`, interactive `config update`, and `config delete` that require confirmation will first let the user choose Chinese or English if the language is not specified.
## Server Deployment Status
The current main path is local MCP stdio usage. Server/team deployment direction only reserves basic functionality:
- Supports specifying configuration files and master keys through environment variables.
- Can run based on Docker in the future.
- Complete HTTP/SSE MCP Server, authentication, multi-tenancy, audit, and web management platform are not within the scope of the first version.
## Troubleshooting
### Cannot find db-lens
Re-execute the installation command and keep the terminal output. If you still cannot run `db-lens` directly after successful installation, it means the installation logic needs repair.
### MCP client cannot see db-lens
First, confirm that the command is available:
```bash
db-lens doctor
db-lens mcp config
```
Then, re-run the corresponding client installation command and restart the client:
```bash
db-lens mcp install-codex
```
### AI cannot find the table
If it is a newly created or renamed table, refresh the table cache once:
```bash
db-lens cache refresh local-dev
```
If multiple databases have tables with the same name, you need to specify the database in the request.
### SQL does not execute EXPLAIN
If SQL uses `?` and other placeholders but does not provide parameters, `db-lens-mcp` will not guess parameter values, so it may only return table structure, index, and risk context, skipping `EXPLAIN`.
