Database MCP Integration

Overview

A Model Context Protocol (MCP) server configuration that gives Claude Code direct, read-safe access to your database. Claude can query tables, inspect schemas, analyze data patterns, debug issues, and generate reports — all through natural language without you writing SQL manually.

Supported Databases

Database	MCP Package	Status
PostgreSQL	@modelcontextprotocol/server-postgres	Production-ready
MySQL	@modelcontextprotocol/server-mysql	Production-ready
SQLite	@modelcontextprotocol/server-sqlite	Production-ready
MongoDB	mcp-mongo-server	Community
Redis	mcp-redis-server	Community
DynamoDB	mcp-dynamodb-server	Community
Supabase	@supabase/mcp-server	Official

Quick Start

PostgreSQL

Copy
// .claude/settings.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/mydb"
      ]
    }
  }
}

MySQL

Copy
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-mysql",
        "--host", "localhost",
        "--port", "3306",
        "--user", "root",
        "--password", "password",
        "--database", "mydb"
      ]
    }
  }
}

SQLite

Copy
{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "--db-path", "./data/app.db"
      ]
    }
  }
}

Supabase

Copy
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server",
        "--supabase-url", "https://your-project.supabase.co",
        "--service-role-key", "your-service-role-key"
      ]
    }
  }
}

Using Environment Variables (Recommended)

Never hardcode credentials. Use environment variables:

Copy
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Or reference your .env file:

Copy
# .env (gitignored)
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

Available MCP Tools

Once connected, Claude can use these database tools:

Schema Inspection

Claude, show me the schema for the users table
Claude, what tables exist in the database?
Claude, list all foreign key relationships
Claude, show indexes on the orders table

Data Queries

Claude, how many active users signed up this month?
Claude, what are the top 10 products by revenue?
Claude, find all orders with status 'pending' older than 7 days
Claude, show me the last 5 error logs

Data Analysis

Claude, what's the average order value by country?
Claude, show me the user retention funnel for the last 30 days
Claude, find duplicate email addresses in the users table
Claude, analyze the distribution of response times in the api_logs table

Debugging

Claude, why is this user's subscription showing as expired?
Claude, trace the order #12345 through all related tables
Claude, find orphaned records in the order_items table
Claude, check if there are any null values in required columns

Safety Configuration

Read-Only Mode (Default)

By default, the MCP server operates in read-only mode:

Copy
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "--read-only"
      ],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Database User Permissions

Create a dedicated read-only database user for Claude:

Copy
-- PostgreSQL: Create read-only user
CREATE ROLE claude_reader WITH LOGIN PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE mydb TO claude_reader;
GRANT USAGE ON SCHEMA public TO claude_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO claude_reader;

-- Explicitly deny dangerous operations
REVOKE CREATE ON SCHEMA public FROM claude_reader;

Copy
-- MySQL: Create read-only user
CREATE USER 'claude_reader'@'localhost' IDENTIFIED BY 'secure_password';
GRANT SELECT ON mydb.* TO 'claude_reader'@'localhost';
FLUSH PRIVILEGES;

Row-Level Security

For sensitive data, use views or row-level security:

Copy
-- Create a view that masks sensitive columns
CREATE VIEW claude_users AS
SELECT
  id,
  email,
  created_at,
  status,
  plan_type,
  '***' AS password_hash,  -- Masked
  '***' AS ssn              -- Masked
FROM users;

-- Grant access only to the view
GRANT SELECT ON claude_users TO claude_reader;
REVOKE SELECT ON users FROM claude_reader;

Query Limits

Prevent runaway queries:

Copy
-- PostgreSQL: Set statement timeout for the user
ALTER ROLE claude_reader SET statement_timeout = '30s';

-- MySQL: Set max execution time
SET GLOBAL max_execution_time = 30000;  -- 30 seconds

Multi-Database Setup

Connect Claude to multiple databases simultaneously:

Copy
{
  "mcpServers": {
    "production-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "--read-only"],
      "env": { "DATABASE_URL": "${PROD_DATABASE_URL}" }
    },
    "analytics-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "--read-only"],
      "env": { "DATABASE_URL": "${ANALYTICS_DATABASE_URL}" }
    },
    "cache": {
      "command": "npx",
      "args": ["-y", "mcp-redis-server"],
      "env": { "REDIS_URL": "${REDIS_URL}" }
    }
  }
}

Then ask Claude:

Claude, compare the user count in production-db vs analytics-db
Claude, check if the user session in cache matches the production-db record

Common Workflows

1. Database Migration Verification

Claude, compare the current schema against the migration files in db/migrations/.
Are there any tables or columns that exist in the schema but aren't in migrations?

2. Data Integrity Checks

Claude, run these checks on the database:
1. Find orders without matching order_items
2. Find users with invalid email formats
3. Check for negative account balances
4. Find records with future created_at dates

3. Performance Analysis

Claude, analyze the slow query log and suggest index improvements.
Which tables are missing indexes on frequently filtered columns?

4. Report Generation

Claude, generate a weekly business report:
- New user signups by day
- Revenue by product category
- Top 10 customers by lifetime value
- Churn rate (users who haven't logged in for 30 days)

5. Schema Documentation

Claude, generate markdown documentation for the entire database schema,
including table descriptions, column types, relationships, and indexes.

Troubleshooting

Connection Refused

Error: connect ECONNREFUSED 127.0.0.1:5432

• Check if the database is running: pg_isready (Postgres) or mysqladmin ping (MySQL)
• Verify the connection string host and port
• Check firewall rules

Authentication Failed

Error: password authentication failed for user "claude_reader"

• Verify credentials in your .env file
• Check pg_hba.conf (Postgres) allows the connection method
• Ensure the user exists: \du in psql

Permission Denied

Error: permission denied for table users

• Grant SELECT permission: GRANT SELECT ON users TO claude_reader;
• Check schema permissions: GRANT USAGE ON SCHEMA public TO claude_reader;

Timeout

Error: Query read timeout

• Reduce query scope (add WHERE clauses, LIMIT)
• Check for missing indexes
• Increase timeout in the MCP server config

Best Practices

1. Always use read-only credentials — Claude should never modify production data through MCP
2. Mask sensitive columns — Use views to hide PII, passwords, and financial data
3. Set query timeouts — Prevent expensive queries from impacting production
4. Use a connection pool — Don't exhaust database connections
5. Connect to replicas — Point Claude at read replicas, not the primary database
6. Audit queries — Enable query logging to track what Claude queries
7. Environment-specific configs — Use different credentials for dev/staging/production
8. Rotate credentials — Regularly rotate the read-only user's password