Configuration

Database MCP is configured through CLI flags and environment variables. This page documents every available option.

Precedence

Configuration values are resolved in this order (highest priority first):

1. CLI flags — explicitly passed on the command line
2. Environment variables — set by the MCP client (via env or envFile in server config)
3. Built-in defaults — backend-aware defaults described below

When the same option is set in multiple places, the higher-priority source wins.

Database Connection

Character Set

Backend Defaults

Default values for --db-port and --db-user depend on the selected backend:

SQLite does not use host, port, or user — only --db-name (the file path) is required.

SSL / TLS

When --db-ssl is enabled, the server validates that any provided certificate paths exist before connecting.

Server Behavior

Security note: Read-only mode is enabled by default. In this mode, write tools (write_query, create_database) are hidden from the AI assistant. Only read tools are available, and read_query enforces SQL validation (SELECT, SHOW, DESCRIBE, USE, EXPLAIN only). Set --read-only=false or MCP_READ_ONLY=false to enable write tools.

HTTP Transport

These options are available only when running in HTTP mode (database-mcp http):

The default stdio transport requires no additional configuration.

Client Configuration Examples

MCP clients configure servers through JSON files. Each tool uses a slightly different file path, but the format is nearly identical. The examples below connect to a local MySQL database.

Claude Code

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "database-mcp": {
      "command": "database-mcp",
      "env": {
        "DB_BACKEND": "mysql",
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "secret",
        "DB_NAME": "myapp"
      }
    }
  }
}

Claude Code also supports HTTP transport for remote servers:

{
  "mcpServers": {
    "database-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:9001/mcp"
    }
  }
}

File locations: .mcp.json (project, shareable) · ~/.claude.json (user, global)

Claude Desktop

Edit the config file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "database-mcp": {
      "command": "database-mcp",
      "env": {
        "DB_BACKEND": "postgres",
        "DB_HOST": "localhost",
        "DB_USER": "postgres",
        "DB_PASSWORD": "secret",
        "DB_NAME": "myapp"
      }
    }
  }
}

Claude Desktop only supports stdio transport. For HTTP mode, use the Connectors UI under Settings > Connectors > Add custom connector.

Cursor

Create .cursor/mcp.json in your project root, or use ~/.cursor/mcp.json for global configuration:

{
  "mcpServers": {
    "database-mcp": {
      "type": "stdio",
      "command": "database-mcp",
      "env": {
        "DB_BACKEND": "mysql",
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_NAME": "myapp"
      },
      "envFile": ".env"
    }
  }
}

Cursor supports envFile to load variables from a .env file. Sensitive values like DB_PASSWORD can be kept there instead of in the JSON config.

Windsurf

Edit the config file at:

• macOS / Linux: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "database-mcp": {
      "command": "database-mcp",
      "env": {
        "DB_BACKEND": "mysql",
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "${env:DB_PASSWORD}",
        "DB_NAME": "myapp"
      }
    }
  }
}

Windsurf supports ${env:VARIABLE_NAME} interpolation to reference values from your shell environment instead of hardcoding them.

Environment Variables vs. envFile