DB Analyzer MCP

A safe, read-only database analysis tool for AI assistants via the Model Context Protocol (MCP). Enables AI to understand your database schema, run analytics queries, and provide insights without any risk of data modification.

Features

• 31 Database Tools - Schema introspection, query execution, performance analysis, and more
• Read-Only by Design - Only SELECT, EXPLAIN, SHOW, and WITH (CTE) queries allowed
• Multi-Layer Security - SQL validation, identifier sanitization, query limits
• PostgreSQL Support - Primary focus with architecture ready for MySQL/SQLite
• Project-Local Config - .db-mcp/ folder for configuration, logs, and cached schema
• Zero Console Output - All logging to files (stdio reserved for MCP protocol)

Installation

# Clone the repository
git clone https://github.com/ariburaco/db-analyzer-mcp.git
cd db-analyzer-mcp

# Install dependencies
bun install

Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "db-analyzer": {
      "command": "bun",
      "args": ["run", "/path/to/db-analyzer-mcp/src/index.ts"]
    }
  }
}

VS Code with Claude Extension

Add to your VS Code settings or .mcp.json:

{
  "mcpServers": {
    "db-analyzer": {
      "command": "bun",
      "args": ["run", "/path/to/db-analyzer-mcp/src/index.ts"]
    }
  }
}

Cursor IDE

Add to Cursor's MCP configuration:

{
  "mcpServers": {
    "db-analyzer": {
      "command": "bun",
      "args": ["run", "/path/to/db-analyzer-mcp/src/index.ts"]
    }
  }
}

Quick Start

1. Initialize your project (creates .db-mcp/ folder):

Use db_init with projectPath="/path/to/your/project"

1. Ensure your .env file has DATABASE_URL:

DATABASE_URL=postgresql://user:password@localhost:5432/mydb

1. Pull your database schema:

Use db_pull to introspect the database

1. Start analyzing:

Use db_tables to see all tables
Use db_describe for table details
Use db_query to run SELECT queries

Tools Reference

Schema Tools

Query Tools

Analytics Tools

Advanced Tools

Monitoring Tools

Extra Tools

Schema Exploration Tools

Supported Query Types

Security

Read-Only Enforcement

Multiple layers of protection ensure no data modification:

1. Statement Whitelist - Only SELECT, EXPLAIN, SHOW, WITH allowed
2. Keyword Blocklist - Blocks INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, etc.
3. SQL Injection Prevention - Identifier validation, table existence checks
4. Row Limits - Configurable max rows (default: 10,000)
5. Query Timeout - Prevents long-running operations
6. Dangerous Pattern Detection - Blocks file operations, backend termination

Blocked Operations

INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE,
GRANT, REVOKE, EXECUTE, CALL, COPY, VACUUM, REINDEX,
CLUSTER, COMMENT, SECURITY, OWNER, SET ROLE, RESET

Project Structure

.db-mcp/                    # Created in your project root
├── config.json             # Configuration file
├── schema/
│   └── snapshot.json       # Schema snapshot for AI
└── logs/
    ├── mcp.log             # General logs
    ├── queries.log         # Query execution logs
    └── errors.log          # Error logs

Configuration Options

.db-mcp/config.json:

Option 1: Using DATABASE_URL (from .env)

{
  "version": "1.0.0",
  "database": {
    "type": "postgresql",
    "envVar": "DATABASE_URL",
    "schema": "public"
  }
}

Option 2: Individual Fields (recommended for special characters in password)

{
  "version": "1.0.0",
  "database": {
    "type": "postgresql",
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "my>complex<password&with$special:chars",
    "database": "mydb",
    "ssl": "no-verify",
    "schema": "public"
  }
}

Option 3: Individual Fields from Environment Variables

{
  "version": "1.0.0",
  "database": {
    "type": "postgresql",
    "hostEnv": "DB_HOST",
    "portEnv": "DB_PORT",
    "userEnv": "DB_USER",
    "passwordEnv": "DB_PASSWORD",
    "databaseEnv": "DB_NAME",
    "ssl": "require",
    "schema": "public"
  }
}

SSL Options

Full Configuration Example

{
  "version": "1.0.0",
  "database": {
    "type": "postgresql",
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "secret",
    "database": "mydb",
    "ssl": "no-verify",
    "schema": "public"
  },
  "driver": {
    "query": "postgres-js",
    "introspection": "drizzle"
  },
  "security": {
    "readOnly": true,
    "maxRowLimit": 10000,
    "queryTimeout": 30000,
    "allowedStatements": ["SELECT", "EXPLAIN", "SHOW", "WITH"]
  },
  "logging": {
    "level": "info",
    "maxFileSize": "10MB",
    "maxFiles": 5
  }
}

Development

# Run in development mode
bun run dev

# Type check
bun run typecheck

# Lint
bun run lint

# Format
bun run format

Tech Stack

• Runtime: Bun - Fast JavaScript runtime
• Language: TypeScript (strict mode)
• MCP SDK: @modelcontextprotocol/sdk
• Schema Introspection: Drizzle Kit
• Database Driver: postgres.js
• Validation: Zod

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Author

Ali Burak Ozden - @ariburaco

Built with Bun and MCP for safe AI-powered database analysis.