mcp-database
A Node.js MCP (Model Context Protocol) server that provides database operations for AI assistants and agents. Supports 40+ databases through genai-toolbox.
Features
- ✅ Easy Installation: Install via npm/npx - no manual binary downloads
- ✅ Universal Database Support: PostgreSQL, MySQL, MongoDB, Redis, SQLite, and 35+ more
- ✅ Simple Configuration: YAML config or environment variables
- ✅ MCP Standard: Full MCP protocol implementation
- ✅ Production Ready: Connection pooling, auth, and observability built-in
Installation
Install from npm and pick the bundle that fits your environment:
- Core package (no bundled binaries, ~50KB):
npm install -g @adversity/mcp-database - Platform-specific (includes binary for one OS/CPU, ~15MB):
- macOS ARM64:
npm install -g @adversity/mcp-database-darwin-arm64 - macOS Intel:
npm install -g @adversity/mcp-database-darwin-x64 - Linux x64:
npm install -g @adversity/mcp-database-linux-x64 - Windows x64:
npm install -g @adversity/mcp-database-win32-x64
- macOS ARM64:
- No install:
npx @adversity/mcp-database --help
Quick Start
Using Prebuilt Configurations
The easiest way to get started is with prebuilt database configurations:
# PostgreSQL
DATABASE_HOST=localhost \
DATABASE_NAME=mydb \
DATABASE_USER=user \
DATABASE_PASSWORD=password \
npx @adversity/mcp-database --prebuilt postgres
# MySQL
DATABASE_HOST=localhost \
DATABASE_NAME=mydb \
DATABASE_USER=root \
DATABASE_PASSWORD=password \
npx @adversity/mcp-database --prebuilt mysql
# SQLite (no credentials needed)
DATABASE_NAME=./my-database.db \
npx @adversity/mcp-database --prebuilt sqlite
# MongoDB
DATABASE_HOST=localhost \
DATABASE_NAME=mydb \
DATABASE_USER=user \
DATABASE_PASSWORD=password \
npx @adversity/mcp-database --prebuilt mongodb
Using Custom Configuration
Create a tools.yaml file:
sources:
my-postgres:
kind: postgres
host: ${POSTGRES_HOST:localhost}
port: ${POSTGRES_PORT:5432}
database: ${POSTGRES_DATABASE:mydb}
user: ${POSTGRES_USER:postgres}
password: ${POSTGRES_PASSWORD}
tools:
get_user_by_id:
kind: postgres-sql
source: my-postgres
description: Get user by ID
parameters:
- name: user_id
type: number
description: The user ID
statement: SELECT * FROM users WHERE id = $1;
Run with custom config:
mcp-database --config tools.yaml
SQLite Built-in Introspection Tools (Recommended for AI)
Designed for AI to explore unknown databases without schema knowledge:
DATABASE_NAME=./your-database.db \
npx @adversity/mcp-database --config prebuilt/sqlite-introspection.yaml
15 Built-in Introspection Tools:
| Tool Set | Tool Name | Function |
|---|---|---|
| Basic Exploration | sqlite_list_tables | List all tables and views |
sqlite_describe_table | View table structure (columns, types, keys) | |
sqlite_list_columns | List all column information | |
sqlite_preview_table | Preview first N rows of data | |
sqlite_database_summary | Complete database summary (tables, indexes, views) | |
| Advanced Analysis | sqlite_list_indexes | List all indexes |
sqlite_list_table_indexes | View indexes for a specific table | |
sqlite_describe_index | View columns in an index | |
sqlite_list_foreign_keys | View foreign key relationships | |
sqlite_get_table_schema | Get table's CREATE statement | |
| Statistics | sqlite_count_rows | Count total rows in a table |
sqlite_table_stats | Get statistics for all tables | |
sqlite_database_info | Database basic information | |
sqlite_get_schema_version | Get schema version number |
Typical AI Workflow:
1. sqlite_list_tables → Discover users, orders, products tables
2. sqlite_describe_table("users") → Understand column structure
3. sqlite_preview_table("users", 5) → See actual data format
4. sqlite_list_foreign_keys("orders") → Understand table relationships
5. Now AI can confidently construct complex queries!
MCP Client Configuration Example:
{
"mcpServers": {
"database": {
"command": "npx",
"args": ["@adversity/mcp-database", "--config", "prebuilt/sqlite-introspection.yaml"],
"env": {
"DATABASE_NAME": "./your-database.db"
}
}
}
}
SQLite Custom YAML Example
- Copy the example:
cp tools.example.yaml tools.yaml - Verify sample database exists:
ls sample.sqlite - Run:
DATABASE_NAME=$(pwd)/sample.sqlite \ npx @adversity/mcp-database --config tools.yaml --verbose - The MCP client can access
sqlite_crudtoolset fromtools.example.yaml:sqlite_list_recent_users: List recent 20 user recordssqlite_get_user_by_id: Query by IDsqlite_find_user_by_email: Search by emailsqlite_create_user/sqlite_update_user_email/sqlite_delete_user: Create/Update/Delete
Example YAML snippet (from tools.example.yaml):
tools:
sqlite_list_recent_users:
kind: sqlite-sql
source: my-sqlite
description: List recent 20 users ordered by creation time
statement: |
SELECT id, name, email, created_at
FROM users
ORDER BY datetime(created_at) DESC
LIMIT 20;
sqlite_create_user:
kind: sqlite-sql
source: my-sqlite
description: Create new user and return result
parameters:
- { name: name, type: string }
- { name: email, type: string }
statement: |
INSERT INTO users (name, email, created_at)
VALUES (?1, ?2, CURRENT_TIMESTAMP)
RETURNING id, name, email, created_at;
toolsets:
sqlite_crud:
- sqlite_list_recent_users
- sqlite_get_user_by_id
- sqlite_find_user_by_email
- sqlite_create_user
- sqlite_update_user_email
- sqlite_delete_user
Unified Environment Variables and CLI Override
All prebuilt databases use simple, unified environment variables:
DATABASE_HOST- Database host (default: localhost)DATABASE_PORT- Database port (default: depends on database type)DATABASE_NAME- Database nameDATABASE_USER- Database userDATABASE_PASSWORD- Database password
You can also override via CLI:
mcp-database --prebuilt postgres \
--db-host prod-db.internal \
--db-port 6543 \
--db-name inventory \
--db-user readonly
自定义 toolbox 端口
默认使用 STDIO 模式，不占用 TCP 端口；当需要切换到 HTTP（例如调试或远程访问）时，可指定传输方式与端口：
npx @adversity/mcp-database --prebuilt sqlite \
--transport http \
--toolbox-host 0.0.0.0 \
--toolbox-port 5900
对应环境变量：
| 变量 | 说明 |
|---|---|
MCP_TOOLBOX_TRANSPORT | stdio（默认）或 http |
MCP_TOOLBOX_HOST | HTTP 监听地址，默认 127.0.0.1 |
MCP_TOOLBOX_PORT | HTTP 端口，默认 5000 |
CLI 也保留 --stdio（布尔）用于兼容旧脚本；推荐使用 --transport 来切换模式。
MCP Integration
Claude Code / Claude Desktop
Add to your .mcp.json or claude_desktop_config.json:
{
"mcpServers": {
"database": {
"command": "npx",
"args": ["@adversity/mcp-database", "--prebuilt", "postgres"],
"env": {
"DATABASE_HOST": "localhost",
"DATABASE_PORT": "5432",
"DATABASE_NAME": "mydb",
"DATABASE_USER": "postgres",
"DATABASE_PASSWORD": "your-password"
}
}
}
}
Cursor IDE
Create .cursor/mcp.json:
{
"mcpServers": {
"database": {
"command": "npx",
"args": ["@adversity/mcp-database", "--prebuilt", "mysql"],
"env": {
"DATABASE_HOST": "localhost",
"DATABASE_NAME": "mydb",
"DATABASE_USER": "root",
"DATABASE_PASSWORD": "your-password"
}
}
}
}
VS Code (Copilot)
Create .vscode/mcp.json:
{
"servers": {
"database": {
"command": "npx",
"args": ["@adversity/mcp-database", "--prebuilt", "postgres"],
"env": {
"DATABASE_HOST": "localhost",
"DATABASE_NAME": "mydb"
}
}
}
}
Windsurf
Configure via the Cascade assistant's MCP settings with the same JSON format as Cursor.
Supported Databases
Relational Databases
- PostgreSQL
- MySQL
- SQL Server
- SQLite
- Oracle
- Cloud SQL (Postgres, MySQL, SQL Server)
- AlloyDB for PostgreSQL
- Spanner
- TiDB
- OceanBase
- YugabyteDB
NoSQL Databases
- MongoDB
- Redis
- Valkey
- Firestore
- Bigtable
- Cassandra
- Couchbase
- Neo4j
- Dgraph
Analytics & Warehouses
- BigQuery
- ClickHouse
- Trino
- Serverless Spark
- Elasticsearch
- SingleStore
Cloud Services
- Looker
- MindsDB
- Dataplex
- Cloud Healthcare API
- Cloud Monitoring
See genai-toolbox documentation for complete list and configuration details.
Available Tools
When connected via MCP, the following tools are available to AI assistants:
list_tables
List all tables in the database with their descriptions.
Example:
Show me all tables in the database
execute_sql
Execute any SQL statement on the database.
Parameters:
sql(string, required): The SQL statement to execute
Example:
Get all users from the users table where age > 25
Environment Variables
All database types use the same unified environment variables:
DATABASE_HOST- Database host (default: localhost)DATABASE_PORT- Database port (default: varies by database type)- PostgreSQL: 5432
- MySQL: 3306
- MongoDB: 27017
- Redis: 6379
- MSSQL: 1433
DATABASE_NAME- Database name or file pathDATABASE_USER- Database userDATABASE_PASSWORD- Database password
For cloud services (Cloud SQL, AlloyDB, BigQuery, Spanner, Firestore), additional GCP-specific variables are required:
GCP_PROJECT- GCP project IDGCP_REGION- GCP region (default: us-central1)CLOUD_SQL_INSTANCE/ALLOYDB_CLUSTER/ etc. - Service-specific identifiers
CLI Reference
mcp-database [OPTIONS]
OPTIONS:
-c, --config <path> Path to tools.yaml configuration file
-p, --prebuilt <type> Use prebuilt config for database type
--db-host <value> Override MCP_DATABASE_HOST（所有预置类型通用）
--db-port <value> Override MCP_DATABASE_PORT
--db-name <value> Override MCP_DATABASE_NAME（对应 database/schema）
--db-user <value> Override MCP_DATABASE_USER
--db-password <value> Override MCP_DATABASE_PASSWORD
--transport <mode> Transport between wrapper 与 toolbox：`stdio`(默认) / `http`
--toolbox-host <value> 当 transport=http 时的监听地址（默认 127.0.0.1）
--toolbox-port <value> 当 transport=http 时的端口（默认 5000）
--stdio Use stdio transport (default: true)
-v, --version Print version
-h, --help Print help
--verbose Enable verbose logging
PREBUILT TYPES:
postgres, mysql, sqlite, mongodb, redis, mssql,
cloud-sql-postgres, cloud-sql-mysql, alloydb-pg,
bigquery, spanner, firestore
Programmatic Usage
You can also use mcp-database programmatically:
import { startServer, generatePrebuiltConfig } from '@adversity/mcp-database';
const config = generatePrebuiltConfig('postgres');
const server = await startServer({
binaryPath: '/path/to/toolbox',
config,
verbose: true,
});
// Server is now running
Testing
The project includes comprehensive test coverage, especially for SQLite features:
# Run all tests
npm test
# Run only SQLite tests
npm test -- sqlite
# Run with coverage
npm run test:coverage
SQLite Test Coverage:
- ✅ 63 test cases, 100% passing
- ✅ Configuration loading and environment variable handling
- ✅ 15 built-in introspection tools validation
- ✅ CRUD operations and parameterized queries
- ✅ Toolset integration tests
Development
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run dev
# Run tests
npm test
# Lint
npm run lint
# Format
npm run format
How It Works
This package wraps the genai-toolbox binary and exposes it as an MCP server:
- Binary Management: Automatically downloads the correct genai-toolbox binary for your platform
- Configuration: Generates or loads YAML configuration with environment variable substitution
- MCP Protocol: Implements MCP server protocol over stdio
- Tool Execution: Proxies tool calls to genai-toolbox subprocess
Requirements
- Node.js 18 or higher
- Internet connection (for initial binary download)
- Database credentials for your target database
License
MIT
Related Projects
- genai-toolbox - The underlying database connectivity engine
- Model Context Protocol - The protocol specification
- @modelcontextprotocol/sdk - MCP SDK
Contributing
Contributions are welcome! Please open an issue or pull request.
Support
- GitHub Issues: Report bugs or request features
- Documentation: genai-toolbox docs