Database MCP setup

A Database MCP setup connects mcp-core to one MySQL, MariaDB-compatible or PostgreSQL database, so Claude can list tables, describe columns and run SQL. You need the Database entitlement, a database user and five required env vars. Read-only is the default, and the safest setup uses a user that only has SELECT.

What do you need before a Database MCP setup?

You need a running mcp-core installation, the Database add-on on the same license and a database that the container can reach over the network. No mcp-core yet? Follow the mcp-core install guide first.

• An active license with the tool:database entitlement, from the Database MCP server add-on.
• Host, port, database name, user and password.
• A seat in My Account → MCP Self-hosted with the Database tool ticked.

Inside the container, localhost is the container itself, not your server. Use a hostname or IP address that the container can reach. Bought the add-on later? Nothing to reinstall: the add-on joins your license, and an email lists the env vars to fill in.

How do you create a read-only user for the Database MCP setup?

Create a dedicated user with only SELECT, on only the tables Claude should see. The tool has its own guardrails, but the database grants are the real enforcement layer. MySQL or MariaDB:

CREATE USER 'claude_ro'@'%' IDENTIFIED BY 'a-long-random-password';
GRANT SELECT ON shopdb.* TO 'claude_ro'@'%';

PostgreSQL:

CREATE ROLE claude_ro LOGIN PASSWORD 'a-long-random-password';
GRANT CONNECT ON DATABASE shopdb TO claude_ro;
GRANT USAGE ON SCHEMA public TO claude_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_ro;

Narrow '%' to the address of your mcp-core server where you can. For write access later, grant INSERT, UPDATE and DELETE on specific tables to a separate user.

Which env vars does the Database MCP setup use?

There are five required variables and five optional ones. Your downloaded .env contains the required lines empty and the optional ones commented out.

Example for a MariaDB database:

DB_TYPE=mysql
DB_HOST=db.internal.example.com
DB_NAME=shopdb
DB_USER=claude_ro
DB_PASSWORD=a-long-random-password

You can also keep these values in My Account → MCP Self-hosted → Tools. They are stored encrypted, a running mcp-core picks them up without a new download, and they override .env.

Which tools does Claude see after the Database MCP setup?

Claude gets three tools, in both modes. Unlike the other add-ons, the write check happens per query, because one SQL tool can read or write.

• database_list_tables: the tables visible to the user. On MySQL and MariaDB this list includes views; on PostgreSQL it shows base tables only, from every schema except the system schemas.
• database_describe_table: column name, data type, nullability and default
• database_query: one SQL statement per call, results capped at DB_MAX_ROWS

How do read-only and read-write differ in a Database MCP setup?

In read-only mode, database_query rejects INSERT, UPDATE and DELETE before they reach the database. Read-write lets those through. Schema changes (CREATE, DROP, ALTER, TRUNCATE, GRANT, REVOKE) are blocked in every mode, and so are multiple statements in one call.

You set the mode per seat when you add it in My Account → MCP Self-hosted → Seats; DB_MODE is the fallback. The keyword check is a safety net, not a guarantee: a SELECT-only database user is what really stops writes. See entitlements vs. tool modes for the difference between buying a tool and its mode.

How do you restart and test the Database MCP setup?

Run the update script from the folder you unzipped:

./mcp-update.sh

Just bought the add-on? Force the license check:

docker exec mcp-core npm run refresh-license

In Claude, run mcp_status first: it shows the license state, the seat and each tool’s mode. Then ask “list the tables in the database”. If you use several clients, check which token belongs to which seat in MCP seats.

Which errors come up during a Database MCP setup?

The messages below come from the tool, so you can search for them directly.

• No database tools at all: the log says “DB_TYPE/DB_HOST/DB_NAME/DB_USER are not fully set”. Fill them in and run ./mcp-update.sh.
• “Unsupported DB_TYPE”: use exactly mysql or postgres.
• “This looks like a write statement (INSERT/UPDATE/DELETE) but this seat is read-only”: expected in read-only mode.
• “Schema-changing statements … are never allowed through this tool”: run schema changes directly against the database.
• “Multiple statements in one call are not allowed”: send one statement per query.
• “No such table (or it has no columns visible to this database user)”: a typo, or the user lacks rights on that table.
• “…showing first 200 of N rows”: narrow the query with WHERE or LIMIT, or raise DB_MAX_ROWS.

A Database MCP setup is finished when database_list_tables returns your tables. The other add-ons are in the MCP setup guides.