@yuuzu/sql-mcp

npm version

A Model Context Protocol (MCP) server for MSSQL, PostgreSQL, and SQLite database operations.

Installation

# Using bunx (recommended)
bunx @yuuzu/sql-mcp

# Using npx
npx @yuuzu/sql-mcp

Features

Multi-database support: MSSQL, PostgreSQL, and SQLite (via better-sqlite3)
8 tools for database operations
Three query modes: safe, write, full
Advanced authentication: Windows Auth (MSSQL), SSL certificates (PostgreSQL)

Tools

Tool	Description
`connect-database`	Connect to a database server
`disconnect`	Disconnect from the current connection
`connection-status`	Check connection status and query mode
`list-databases`	List all databases on the server
`switch-database`	Switch to a different database
`list-tables`	List all tables and views
`describe-table`	Get table schema details
`execute-query`	Execute SQL queries

Query Modes

Control query permissions via SQL_MCP_MODE environment variable:

Mode	Allowed Operations	Description
`safe` (default)	SELECT, WITH, EXPLAIN	Read-only, safest
`write`	+ INSERT, UPDATE, DELETE	Allows data modification
`full`	+ CREATE, DROP, ALTER, TRUNCATE	Full access, use with caution

Note: PRAGMA statements (e.g. PRAGMA table_info(users)) are allowed in all modes including safe, as they are read-only metadata queries commonly used with SQLite.

# Example: Enable write mode
SQL_MCP_MODE=write bunx @yuuzu/sql-mcp

Usage Examples

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "sql-mcp": {
            "command": "bunx",
            "args": ["@yuuzu/sql-mcp"],
            "env": {
                "SQL_MCP_MODE": "safe"
            }
        }
    }
}

Connect to MSSQL

{
    "tool": "connect-database",
    "arguments": {
        "engine": "mssql",
        "server": "localhost",
        "port": 1433,
        "user": "sa",
        "password": "your_password",
        "database": "master"
    }
}

Connect to PostgreSQL

{
    "tool": "connect-database",
    "arguments": {
        "engine": "postgres",
        "server": "localhost",
        "port": 5432,
        "user": "postgres",
        "password": "your_password",
        "database": "postgres"
    }
}

Connect with Windows Authentication (MSSQL)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "mssql",
        "server": "localhost",
        "windowsAuth": true
    }
}

Connect with SSL (PostgreSQL)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "postgres",
        "server": "your-server.com",
        "user": "postgres",
        "password": "your_password",
        "ssl": {
            "rejectUnauthorized": true,
            "ca": "/path/to/ca-certificate.crt"
        }
    }
}

Connect to SQLite (file)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "sqlite",
        "filename": "/absolute/path/to/database.db"
    }
}

Connect to SQLite (in-memory)

Useful for testing, demos, or ephemeral scratch workspaces.

{
    "tool": "connect-database",
    "arguments": {
        "engine": "sqlite",
        "filename": ":memory:"
    }
}

Connect to SQLite (read-only)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "sqlite",
        "filename": "/absolute/path/to/database.db",
        "readonly": true,
        "fileMustExist": true
    }
}

SQLite runtime note: SQLite support uses better-sqlite3 which requires Node.js. When running via bunx, MSSQL and PostgreSQL work normally but SQLite connections will return a clear error directing you to use npx or node instead.

Development

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Run tests with coverage
bun test --coverage

# Build
bun run build

# Type check
bun run typecheck

Release

Releases are automated via GitHub Actions. To create a new release:

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0

This will:

Build the project
Publish to npm with provenance
Create a GitHub Release with auto-generated release notes

Requirements: Set NPM_TOKEN secret in your GitHub repository settings.

License

MIT

sql-mcp