Configuration

Configure dbmcp with CLI flags, environment variables, and backend-specific defaults

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):

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

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

Database Connection

CLI Flag	Environment Variable	Default	Description
`--db-backend`	`DB_BACKEND`	`mysql`	Database backend: `mysql`, `mariadb`, `postgres`, `sqlite`
`--db-host`	`DB_HOST`	`localhost`	Database host
`--db-port`	`DB_PORT`	Backend-dependent	Database port (see Backend Defaults)
`--db-user`	`DB_USER`	Backend-dependent	Database user (see Backend Defaults)
`--db-password`	`DB_PASSWORD`	—	Database password
`--db-name`	`DB_NAME`	—	Database name, or file path for SQLite

Character Set

CLI Flag	Environment Variable	Default	Description
`--db-charset`	`DB_CHARSET`	—	Character set (MySQL/MariaDB only)

Backend Defaults

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

Backend	Default Port	Default User
MySQL	`3306`	`root`
MariaDB	`3306`	`root`
PostgreSQL	`5432`	`postgres`
SQLite	N/A	N/A

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

SSL / TLS

CLI Flag	Environment Variable	Default	Description
`--db-ssl`	`DB_SSL`	`false`	Enable SSL for the database connection
`--db-ssl-ca`	`DB_SSL_CA`	—	Path to CA certificate
`--db-ssl-cert`	`DB_SSL_CERT`	—	Path to client certificate
`--db-ssl-key`	`DB_SSL_KEY`	—	Path to client key
`--db-ssl-verify-cert`	`DB_SSL_VERIFY_CERT`	`true`	Verify the server certificate

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

Server Behavior

CLI Flag	Environment Variable	Default	Description
`--db-read-only`	`DB_READ_ONLY`	`true`	Enable read-only mode
`--db-max-pool-size`	`DB_MAX_POOL_SIZE`	`5`	Maximum database connection pool size
`--db-connection-timeout`	`DB_CONNECTION_TIMEOUT`	—	Connection timeout in seconds
`--db-query-timeout`	`DB_QUERY_TIMEOUT`	`30`	Query execution timeout in seconds
`--db-page-size`	`DB_PAGE_SIZE`	`100`	Max items per paginated tool response (range 1–500)
`--log-level`	`LOG_LEVEL`	`info`	Log level: `error`, `warn`, `info`, `debug`, `trace`

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

The page size applies uniformly to every paginated tool; see the Cursor Pagination section on the Features page for the full protocol.

HTTP Transport

These options are available only when running in HTTP mode (dbmcp http):

CLI Flag	Default	Description
`--host`	`127.0.0.1`	Bind host for the HTTP server
`--port`	`9001`	Bind port for the HTTP server
`--allowed-origins`	`http://localhost,http://127.0.0.1,https://localhost,https://127.0.0.1`	Allowed CORS origins (comma-separated)
`--allowed-hosts`	`localhost,127.0.0.1`	Allowed host names (comma-separated)

A transport subcommand is required — running dbmcp with no subcommand prints usage help and exits with a non-zero status. The stdio transport requires no additional configuration beyond the database options above.

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": {
    "dbmcp": {
      "command": "dbmcp",
      "args": ["stdio"],
      "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": {
    "dbmcp": {
      "type": "http",
      "url": "http://127.0.0.1:9001/mcp"
    }
  }
}

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

Using Docker:

{
  "mcpServers": {
    "dbmcp": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "DB_BACKEND", "-e", "DB_HOST", "-e", "DB_USER",
        "-e", "DB_PASSWORD", "-e", "DB_NAME",
        "ghcr.io/haymon-ai/dbmcp"
      ],
      "env": {
        "DB_BACKEND": "postgres",
        "DB_HOST": "host.docker.internal",
        "DB_USER": "postgres",
        "DB_PASSWORD": "secret",
        "DB_NAME": "myapp"
      }
    }
  }
}

Claude Desktop

Edit the config file at:

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dbmcp": {
      "command": "dbmcp",
      "args": ["stdio"],
      "env": {
        "DB_BACKEND": "postgres",
        "DB_HOST": "localhost",
        "DB_USER": "postgres",
        "DB_PASSWORD": "secret",
        "DB_NAME": "myapp"
      }
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "dbmcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "DB_BACKEND", "-e", "DB_HOST", "-e", "DB_USER",
        "-e", "DB_PASSWORD", "-e", "DB_NAME",
        "ghcr.io/haymon-ai/dbmcp"
      ],
      "env": {
        "DB_BACKEND": "postgres",
        "DB_HOST": "host.docker.internal",
        "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": {
    "dbmcp": {
      "type": "stdio",
      "command": "dbmcp",
      "args": ["stdio"],
      "env": {
        "DB_BACKEND": "mysql",
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_NAME": "myapp"
      },
      "envFile": ".env"
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "dbmcp": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "DB_BACKEND", "-e", "DB_HOST", "-e", "DB_USER",
        "-e", "DB_PASSWORD", "-e", "DB_NAME",
        "ghcr.io/haymon-ai/dbmcp"
      ],
      "env": {
        "DB_BACKEND": "mysql",
        "DB_HOST": "host.docker.internal",
        "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:

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

{
  "mcpServers": {
    "dbmcp": {
      "command": "dbmcp",
      "args": ["stdio"],
      "env": {
        "DB_BACKEND": "mysql",
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "${env:DB_PASSWORD}",
        "DB_NAME": "myapp"
      }
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "dbmcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "DB_BACKEND", "-e", "DB_HOST", "-e", "DB_USER",
        "-e", "DB_PASSWORD", "-e", "DB_NAME",
        "ghcr.io/haymon-ai/dbmcp"
      ],
      "env": {
        "DB_BACKEND": "mysql",
        "DB_HOST": "host.docker.internal",
        "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`

Feature	Claude Code	Claude Desktop	Cursor	Windsurf
`env` object	Yes	Yes	Yes	Yes
`envFile`	No	No	Yes	No
Variable interpolation	`${VAR}`	No	`${env:VAR}`	`${env:VAR}`
HTTP transport in config	Yes	No	Yes	Yes
Project-scoped config	Yes	No	Yes	No

On this page