MCP Database Server MCP Server

@nam088/mcp-database-server

MCP (Model Context Protocol) server for multiple database types, designed with a modular architecture for easy extensibility.

📖 Read in Vietnamese: README.vi.md

Features

The server provides the following tools:

• query: Execute SELECT queries and return results
• execute_sql: Execute any SQL command (INSERT, UPDATE, DELETE, CREATE, etc.)
• list_tables: List all tables in the database
• describe_table: Get detailed information about a table's schema

Architecture

The project is split into separate modules:

src/
├── index.ts              # Entry point, initializes adapter based on DB_TYPE
├── server.ts             # MCP server implementation
└── adapters/
    ├── base.ts           # Base adapter interface
    ├── postgres.ts       # PostgreSQL adapter implementation
    ├── mysql.ts          # MySQL adapter implementation
    ├── sqlite.ts         # SQLite adapter implementation
    ├── redis.ts          # Redis adapter implementation
    ├── mongo.ts          # MongoDB adapter implementation
    └── ldap.ts           # LDAP adapter implementation

Database Adapters

Each database has its own adapter implementing the DatabaseAdapter interface:

• PostgresAdapter: PostgreSQL support with 13 SQL tools
• MySQLAdapter: MySQL/MariaDB support with 13 SQL tools
• SQLiteAdapter: SQLite support with 13 SQL tools (using better-sqlite3)
• RedisAdapter: Redis support with 16 Redis tools
• MongoAdapter: MongoDB support with 15 MongoDB tools
• LDAPAdapter: LDAP support with 6 LDAP tools

Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

Configuration

Environment Variables

• DB_TYPE: Database type (default: postgres)

  • postgres or postgresql: PostgreSQL
  • mysql or mysql2: MySQL/MariaDB
  • sqlite: SQLite
  • redis: Redis
  • mongodb or mongo: MongoDB
  • ldap: LDAP

• READ_ONLY_MODE: Read-only mode (default: true - safer)

  • true or not set: Only allows reads, blocks all write operations (default)
  • false or 0: Allows both read and write (must be set explicitly)

• POSTGRES_CONNECTION_STRING: Connection string for PostgreSQL

• MYSQL_CONNECTION_STRING or MYSQL_URL: Connection string for MySQL

• SQLITE_CONNECTION_STRING or SQLITE_URL: Connection string for SQLite (file path)

• REDIS_CONNECTION_STRING or REDIS_URL: Connection string for Redis

• MONGODB_CONNECTION_STRING or MONGODB_URL: Connection string for MongoDB

• LDAP_CONNECTION_STRING or LDAP_URL: Connection string for LDAP

• LDAP_BIND_DN: Bind DN for LDAP authentication (optional)

• LDAP_BIND_PASSWORD: Bind password for LDAP authentication (optional)

• DATABASE_URL: Connection string (fallback for PostgreSQL, MySQL, or SQLite)

Examples:

# PostgreSQL with read-only mode (default, no need to set READ_ONLY_MODE)
export DB_TYPE="postgres"
export POSTGRES_CONNECTION_STRING="postgresql://user:password@localhost:5432/mydb"
# READ_ONLY_MODE defaults to true

# Redis with write access (must be set explicitly)
export DB_TYPE="redis"
export REDIS_CONNECTION_STRING="redis://localhost:6379"
export READ_ONLY_MODE="false"

# MySQL with read-only mode (default)
export DB_TYPE="mysql"
export MYSQL_CONNECTION_STRING="mysql://user:password@localhost:3306/mydb"
# READ_ONLY_MODE defaults to true

# SQLite with read-only mode (default)
export DB_TYPE="sqlite"
export SQLITE_CONNECTION_STRING="sqlite://./database.sqlite"
# READ_ONLY_MODE defaults to true

# MongoDB with read-only mode (default)
export DB_TYPE="mongodb"
export MONGODB_CONNECTION_STRING="mongodb://localhost:27017/mydb"
# READ_ONLY_MODE defaults to true

Usage

Using npx (Recommended)

After publishing, you can run the server directly with npx without installing:

npx @nam088/mcp-database-server

Local Development

Run the server locally:

npm start

Or run in development mode with watch:

npm run dev

MCP Client Configuration

Add the server to your MCP client configuration (e.g., Claude Desktop). You can use either npx (recommended) or node with a local path.

Using npx (Recommended)

The easiest way is to use npx, which will automatically download and run the package:

{
  "mcpServers": {
    "postgres-readonly": {
      "command": "npx",
      "args": ["-y", "@nam088/mcp-database-server"],
      "env": {
        "DB_TYPE": "postgres",
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

Note: The -y flag automatically accepts package installation if not already present.

Using Local Installation

If you prefer to install locally or use a specific path:

{
  "mcpServers": {
    "postgres-readonly": {
      "command": "node",
      "args": ["/path/to/database-server/dist/index.js"],
      "env": {
        "DB_TYPE": "post