How do I use DB CLI MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DB CLI MCP Server show the first 10 records from the users table" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

DB CLI MCP Server

License: MIT Node.js MCP

繁體中文版 README

A Model Context Protocol (MCP) Server that provides a unified, safe, AI-friendly interface for executing read-only database queries across multiple databases via CLI tools.

Features

Multi-database support — SQL Server, MySQL, MariaDB, PostgreSQL, Oracle
Read-only enforcement — Strict SELECT-only query execution with fail-closed validation
Zero-config startup — Server starts even without config files or CLI tools installed
Auto-detection — Scans project files (.env, appsettings.json, docker-compose.yml, etc.) for DB configs
Temporary connections — Ephemeral, in-memory-only connections that never touch disk
CLI tool guidance — Detects missing CLI tools and provides installation instructions
AI-native — Built for seamless integration with AI IDEs and CLI tools via MCP protocol

Supported Databases

Database	CLI Tool	Default Port
SQL Server	`sqlcmd`	1433
MySQL	`mysql`	3306
MariaDB	`mariadb`	3306
PostgreSQL	`psql`	5432
Oracle	`sqlplus`	1521

Installation

Prerequisites

Node.js 18 or later
At least one database CLI tool installed (optional — server works without them)

Install via npm

npm install -g @mcp/dbcli-server

Install from source

git clone https://github.com/your-org/dbcli-mcp-server.git
cd dbcli-mcp-server
npm install
npm run build

Quick Start

1. Run the server

# Via npx (no install needed)
npx @mcp/dbcli-server --stdio

# Or if installed globally
dbcli-mcp-server --stdio

2. Check system status

Use the doctor tool to verify CLI tools and configuration:

{
  "serverVersion": "2.0",
  "cliStatus": [
    { "dbType": "mssql", "cli": "sqlcmd", "installed": true, "version": "17.10" },
    { "dbType": "mysql", "cli": "mysql", "installed": false }
  ],
  "issues": ["mysql not installed"]
}

3. Run a query

// Input
{ "sql": "SELECT * FROM users LIMIT 10" }

// Output
{
  "success": true,
  "columns": ["id", "name", "email"],
  "rows": [
    { "id": "1", "name": "Alice", "email": "alice@example.com" }
  ],
  "rowCount": 1,
  "truncated": false
}

AI IDE & CLI Integration

Claude Code

Claude Code supports MCP servers natively.

Setup

Add the server to your Claude Code MCP configuration:

claude mcp add dbcli -- npx @mcp/dbcli-server --stdio

Or manually edit ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@mcp/dbcli-server", "--stdio"]
    }
  }
}

Usage

Once configured, you can ask Claude Code directly:

> Query the users table to show the first 10 records
> Check which database CLI tools are installed on my system
> Create a temporary connection to my local MySQL database
> Scan this project for database configurations

Codex CLI

Codex CLI supports MCP protocol integration.

Setup

Add to your Codex CLI configuration file ~/.codex/config.json:

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@mcp/dbcli-server", "--stdio"]
    }
  }
}

Usage

codex "Query the users table in my local SQL Server database"
codex "What database configurations exist in this project?"

Cursor

Cursor supports MCP servers for AI-assisted development.

Setup

Open Cursor Settings: Ctrl+Shift+J (Windows/Linux) or Cmd+Shift+J (macOS)
Navigate to MCP section
Click "Add new MCP server"
Fill in the configuration:

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@mcp/dbcli-server", "--stdio"]
    }
  }
}

Or manually edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@mcp/dbcli-server", "--stdio"]
    }
  }
}

Usage

In Cursor's AI chat or Composer, you can:

@dbcli Run SELECT * FROM products WHERE price > 100
@dbcli Show me the database schema for the orders table
@dbcli Create a temporary connection to postgres://localhost:5432/mydb

VS Code (Copilot)

VS Code with GitHub Copilot supports MCP servers (requires Copilot Chat).

Setup

Install the GitHub Copilot and GitHub Copilot Chat extensions
Open VS Code Settings (Ctrl+,)
Search for mcp in settings
Edit settings.json and add:

{
  "github.copilot.chat.mcp.servers": {
    "dbcli": {
      "command": "npx",
      "args": ["@mcp/dbcli-server", "--stdio"]
    }
  }
}

Or create .vscode/mcp.json in your project:

{
  "servers": {
    "dbcli": {
      "command": "npx",
      "args": ["@mcp/dbcli-server", "--stdio"]
    }
  }
}

Usage

In Copilot Chat panel:

@dbcli What database connections are configured in this project?
@dbcli Run a health check on my database setup
@dbcli SELECT COUNT(*) FROM orders WHERE status = 'pending'

GitHub Copilot CLI

GitHub Copilot CLI can leverage MCP servers.

Setup

Configure via ~/.config/github-copilot/config.json:

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@mcp/dbcli-server", "--stdio"]
    }
  }
}

Usage

gh copilot explain "How to query my database using the dbcli MCP server"

Visual Studio 2026

Visual Studio 2026 supports MCP servers through its AI integration.

Setup

Open Tools → Options → GitHub Copilot → MCP Servers
Click "Add Server"
Configure:
- Name: dbcli
- Command: npx
- Arguments: @mcp/dbcli-server --stdio

Or edit .vs/mcp.json in your solution root:

{
  "servers": {
    "dbcli": {
      "command": "npx",
      "args": ["@mcp/dbcli-server", "--stdio"]
    }
  }
}

Usage

In the Copilot Chat window:

@dbcli Query the Customers table for records from this month
@dbcli Check if sqlcmd is installed and show install instructions if not

MCP Tools Reference

`doctor()`

Returns system diagnostics including server version, CLI tool installation status, and detected issues.

Parameters: None

Response:

{
  "serverVersion": "2.0",
  "cliStatus": [
    { "dbType": "mssql", "cli": "sqlcmd", "installed": true, "version": "17.10", "path": "/usr/bin/sqlcmd" }
  ],
  "issues": []
}

`scanProjectDbConfigs()`

Scans current project directory for database configuration in common config files.

Scanned files: .env, .env.*, appsettings.json, application.yml, application.properties, docker-compose.yml

Parameters: None

Response:

[
  {
    "dbType": "mssql",
    "host": "localhost",
    "port": 1433,
    "database": "ExampleDB",
    "source": "appsettings.json"
  }
]

`initConfig()`

Creates or updates a persistent configuration profile in .mcp/dbcli.config.json.

Parameters:

Parameter	Type	Required	Description
profileName	string	Yes	Profile name (e.g., "dev")
dbType	string	Yes	Database type
host	string	Yes	Database host
database	string	Yes	Database name
port	number	No	Database port
username	string	No	Database username
password	string	No	Database password
timeoutSeconds	number	No	Query timeout (default: 30)
maxRows	number	No	Max rows returned (default: 500)

`setActiveProfile()`

Switches the active configuration profile.

Parameters:

Parameter	Type	Required	Description
profileName	string	Yes	Profile name to activate

`getInstallInstructions()`

Returns platform-specific installation instructions for a database CLI tool.

Parameters:

Parameter	Type	Required	Description
dbType	string	Yes	Database type

Response:

{
  "dbType": "mssql",
  "cli": "sqlcmd",
  "installed": false,
  "instructions": {
    "windows": "winget install Microsoft.SQLCMD",
    "linux": "sudo apt install mssql-tools",
    "macos": "brew install mssql-tools"
  }
}

`createTemporaryConnection()`

Creates an in-memory-only database connection that is never persisted to disk.

Parameters:

Parameter	Type	Required	Description
dbType	string	Yes	Database type
host	string	Yes	Database host
database	string	Yes	Database name
port	number	No	Database port
username	string	No	Database username
password	string	No	Database password

Response:

{
  "id": "uuid-string",
  "type": "temporary",
  "dbType": "mssql",
  "cli": "sqlcmd",
  "connection": {
    "host": "localhost",
    "database": "TestDB",
    "password": "***"
  }
}

`runSelectQuery()`

Executes a read-only SQL query through the appropriate database CLI tool.

Parameters:

Parameter	Type	Required	Description
sql	string	Yes	The SELECT SQL query
connectionId	string	No	Temporary connection ID (uses active profile if omitted)

Allowed SQL:

SELECT ...
WITH ... SELECT ... (CTE)
EXPLAIN SELECT ...

Response:

{
  "success": true,
  "columns": ["id", "name"],
  "rows": [{ "id": "1", "name": "Alice" }],
  "rowCount": 1,
  "truncated": false
}

Connection Modes

Mode	Description	Persistence
Project Detection	Auto-detects connection info from project files	None
Config Profile	Stored in `.mcp/dbcli.config.json`	Disk
Temporary Connection	Runtime-only, created via `createTemporaryConnection()`	Memory only

Config File Structure

{
  "version": 1,
  "activeProfile": "dev",
  "profiles": {
    "dev": {
      "dbType": "mssql",
      "cli": "sqlcmd",
      "connection": {
        "host": "localhost",
        "port": 1433,
        "database": "ExampleDb",
        "username": "app",
        "password": "${DB_PASSWORD}"
      },
      "limits": {
        "timeoutSeconds": 30,
        "maxRows": 500
      }
    }
  }
}

Security

Core Security Rules

SELECT-only queries — All DML/DDL operations are strictly forbidden
Fail-closed validation — If the SQL parser cannot determine the query type, it is rejected
No credential exposure — Passwords are masked in all API responses
Result size limits — maxRows prevents excessive data retrieval
Query timeouts — timeoutSeconds kills long-running queries
No shell injection — CLI execution uses execFile (not exec), preventing shell injection
Multi-statement rejection — Semicolon-separated multi-statement queries are blocked
Temporary connection isolation — Ephemeral connections are never written to disk

Forbidden SQL Operations

INSERT, UPDATE, DELETE, MERGE, CREATE, ALTER, DROP, TRUNCATE, EXEC, EXECUTE, CALL, GRANT, REVOKE, SELECT INTO

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Project Structure

src/
├── index.ts                  # MCP Server entry point + tool definitions
├── types.ts                  # Core TypeScript types
├── server/
│   └── ConnectionStore.ts    # Temporary connection memory store
├── validator/
│   └── SqlValidator.ts       # SQL security validation
├── cli/
│   ├── CliManager.ts         # CLI detection + install instructions
│   └── CliExecutor.ts        # Safe CLI execution
├── config/
│   └── ConfigManager.ts      # Configuration file management
├── scanner/
│   └── ProjectScanner.ts     # Project DB config scanning
└── formatter/
    └── ResultFormatter.ts    # Query result formatting

Architecture

AI Client (Claude Code / Cursor / VS Code / Codex CLI / ...)
    │
    │  MCP Protocol (JSON-RPC over stdio)
    ▼
┌──────────────────────────────┐
│       MCP Server Core        │
│   (Tool Routing & Lifecycle) │
└──────────┬───────────────────┘
           │
     ┌─────┼─────┬──────────┬──────────┬──────────┐
     ▼     ▼     ▼          ▼          ▼          ▼
  Project  CLI   Config     SQL       CLI       Result
  Scanner  Mgr   Manager  Validator  Executor  Formatter

License

MIT License. See LICENSE for details.

DB CLI MCP Server

Table of Contents

Features

Supported Databases

Installation

Prerequisites

Install via npm

Install from source

Quick Start

1. Run the server

2. Check system status

3. Run a query

AI IDE & CLI Integration

Claude Code

Setup

Usage

Codex CLI

Setup

Usage

Cursor

Setup

Usage

VS Code (Copilot)

Setup

Usage

GitHub Copilot CLI

Setup

Usage

Visual Studio 2026

Setup

Usage

MCP Tools Reference

doctor()

scanProjectDbConfigs()

initConfig()

setActiveProfile()

getInstallInstructions()

createTemporaryConnection()

runSelectQuery()

Connection Modes

Config File Structure

Security

Core Security Rules

Forbidden SQL Operations

Development

Project Structure

Architecture

License

Resources

Looking for Admin?

Appeared in Searches

Latest Blog Posts

MCP directory API

`doctor()`

`scanProjectDbConfigs()`

`initConfig()`

`setActiveProfile()`

`getInstallInstructions()`

`createTemporaryConnection()`

`runSelectQuery()`