Cubrid

cubrid-mcp-server

A Model Context Protocol server for CUBRID, enabling LLMs to safely inspect schemas and execute read-only queries via pycubrid.

Terminal recording of a real MCP stdio session (demos/mcp_demo.py, recorded with demos/record_demo.sh).

Start here

New to CUBRID or to MCP? Follow the Quick Start guide. It starts a disposable local CUBRID lab, prepares a sample table and a dedicated read-only account, connects one MCP client (a short Python script) and runs a first query, showing what each result means and how to clean up. The sections below are the reference for configuration, tools and client setup.

Features

Resources

Schema metadata is also exposed as read-only MCP Resources, so clients can discover and read schema context without a tool call. Resources reuse the same read-only catalog queries as the tools — no additional data access or write surface.

Schema resources always read the default connection (see Multi-Connection). The guides are static Markdown. Table names in {table} are percent-decoded by URI-template matching; an unknown or system table produces a resource-read error, matching the describe_table tool.

Prompts

The server also exposes a small set of MCP Prompt templates — reusable, guided starting points for common inspection tasks. Prompts are guidance-only: each one returns text that tells the client which of the existing read-only tools to call and in what order. They never touch the database, execute SQL, or add any new data-access surface, and any argument you pass is fenced and treated strictly as untrusted data. The prompts are advisory templates only — the actual read-only enforcement remains in the underlying tools (execute_query/explain_query via safety.py).

Quick Start

The values below are placeholders for your own database and account. The Quick Start guide walks through the same settings with a prepared lab, using the account mcp_reader from SECURITY.md.

Configure

Set the required environment variables:

export CUBRID_HOST=localhost
export CUBRID_PORT=33000        # optional, default: 33000
export CUBRID_USER=readonly_user   # a CUBRID user with SELECT-only grants (see Security)
export CUBRID_PASSWORD=secret
export CUBRID_DATABASE=mydb

Optional settings:

Multiple connections

By default the bare CUBRID_* variables define a single connection named default. You can serve additional CUBRID databases from the same process by listing extra connection names in CUBRID_CONNECTIONS (comma-separated) and providing CUBRID_<NAME>_* variables for each. Every tool accepts an optional connection argument selecting which connection to target; omitting it (or passing default) uses the bare-variable connection, so existing single-database setups are unchanged.

# Default connection (unchanged)
export CUBRID_HOST=localhost
export CUBRID_USER=readonly_user
export CUBRID_PASSWORD=secret
export CUBRID_DATABASE=mydb

# Additional named connections
export CUBRID_CONNECTIONS=reporting,analytics

export CUBRID_REPORTING_HOST=reporting-db
export CUBRID_REPORTING_USER=readonly_user
export CUBRID_REPORTING_PASSWORD=secret
export CUBRID_REPORTING_DATABASE=reports
export CUBRID_REPORTING_MCP_MAX_ROWS=500   # optional per-connection tuning

export CUBRID_ANALYTICS_HOST=analytics-db
export CUBRID_ANALYTICS_USER=readonly_user
export CUBRID_ANALYTICS_PASSWORD=secret
export CUBRID_ANALYTICS_DATABASE=analytics

Notes:

• Connection names must match [A-Za-z0-9_]+ and are matched case-insensitively.
• default is reserved (it always comes from the bare CUBRID_* variables) and cannot appear in CUBRID_CONNECTIONS.
• For a named connection <NAME>, connection fields live at CUBRID_<NAME>_HOST etc. and the optional MCP tuning knobs at CUBRID_<NAME>_MCP_* (same suffixes as the global ones). Named connections do not inherit values from the bare vars.
• Selecting an unknown connection returns a clear error listing the available names.
• Each connection has its own read-only enforcement, so a named connection can set CUBRID_<NAME>_MCP_READONLY independently of the default.

Run

Check the install without a database:

cubrid-mcp-server --help
cubrid-mcp-server --version

Both flags exit 0 and print to stderr. They do not read CUBRID_* or start the MCP loop.

Run from PyPI

Use uvx to run directly from PyPI:

uvx cubrid-mcp-server

Or with pipx:

pipx run cubrid-mcp-server

Run from source

git clone https://github.com/cubrid-lab/cubrid-mcp-server.git
cd cubrid-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -e .
cubrid-mcp-server

MCP Client Integration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cubrid": {
      "command": "uvx",
      "args": ["cubrid-mcp-server"],
      "env": {
        "CUBRID_HOST": "localhost",
        "CUBRID_USER": "readonly_user",
        "CUBRID_PASSWORD": "secret",
        "CUBRID_DATABASE": "mydb"
      }
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "cubrid": {
      "command": "uvx",
      "args": ["cubrid-mcp-server"],
      "env": {
        "CUBRID_HOST": "localhost",
        "CUBRID_USER": "readonly_user",
        "CUBRID_PASSWORD": "secret",
        "CUBRID_DATABASE": "mydb"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "cubrid": {
      "command": "uvx",
      "args": ["cubrid-mcp-server"],
      "env": {
        "CUBRID_HOST": "localhost",
        "CUBRID_USER": "readonly_user",
        "CUBRID_PASSWORD": "secret",
        "CUBRID_DATABASE": "mydb"
      }
    }
  }
}

Security

The server is read-only by default. A code-level SQL whitelist allows only SELECT, SHOW, DESC, DESCRIBE, and WITH statements. Multi-statement queries are rejected. CUBRID has no EXPLAIN statement; use the explain_query tool for execution plans (it executes the statement under SET TRACE ON and rolls back).

Read-only mode also rejects INCR, DECR, serial advances (NEXT_VALUE, NEXTVAL, SERIAL_NEXT_VALUE) and the click counter WITH INCREMENT FOR: they change data inside a SELECT, the rollback does not undo them, and a SELECT-only grant does not prevent them. See the Security Model.

The SQL keyword checks are a guardrail and defense-in-depth, not a security boundary. The primary control is a dedicated least-privilege database account: run the server as a CUBRID user that has SELECT only on the tables the model needs, never reuse dba or the owner account, and keep the account to the minimum privileges required, with no DDL rights. See SECURITY.md.

For production use, also configure a read-only database user. See SECURITY.md for the recommended setup.

Write mode (opt-in)

Write access is disabled by default. Setting CUBRID_MCP_WRITE=1 registers an additional execute_write tool that accepts a single INSERT, UPDATE, or DELETE statement and runs it in an explicit transaction (commit on success, rollback on any error). When write mode is off the tool is not registered at all, so no write path is exposed in MCP capability discovery. With multiple connections configured, the tool is registered when any connection enables writes (via CUBRID_MCP_WRITE or CUBRID_<NAME>_MCP_WRITE).

Constraints and rationale:

• Single-statement DML only. Standalone reads, DDL (CREATE/ALTER/DROP/TRUNCATE), transaction-control, and multi-statement input are rejected. (A single DML statement may still legally contain subqueries, e.g. INSERT ... SELECT.)
• DDL is intentionally unsupported. execute_write is a DML tool (INSERT/UPDATE/DELETE) and execute_query is read-only, so CREATE/ALTER/DROP/TRUNCATE are rejected by both. (The server runs pycubrid with autocommit off; on the CUBRID versions tested (10.2, 11.2, 11.4) DDL is transactional and is rolled back if it is not committed, so the exclusion rests on the tool contracts, not on DDL auto-commit.)
• Write mode is per-connection. execute_write accepts the same optional connection argument as the read tools and runs against that connection; a connection whose CUBRID_<NAME>_MCP_WRITE is off refuses the write even when another connection enables it.
• execute_query never becomes a write path through the write-mode flag or CUBRID_MCP_READONLY: with CUBRID_MCP_READONLY=0 it still rejects write, DDL and transaction-control statements, method calls (CALL, EVALUATE) and KILL before they run, so CALL login(...) cannot change the session user, rejects INCR, DECR, serial advances and the click counter, which change data inside a SELECT, and rolls back any statement that returns no result set. Clients that sent writes through execute_query with CUBRID_MCP_READONLY=0 must switch to execute_write.
• Enforcement is defense-in-depth; still run the server as a CUBRID user granted only the privileges it needs. See SECURITY.md.

Logging

The server speaks the MCP stdio transport, where stdout carries the JSON-RPC protocol stream. Anything written to stdout by the server or its dependencies will corrupt that stream and break the client connection. For this reason all logging is routed to stderr, and you should keep it that way: when adding custom logging or diagnostics, never print() to stdout — use the standard logging module (which is configured to emit on stderr) or write to stderr explicitly. The log level defaults to INFO.

Errors surfaced back to the LLM client are sanitized: only the exception category (e.g. query failed: OperationalError) is returned, while the full exception detail is logged to stderr for operators. This keeps schema details, hostnames, SQL fragments, and configuration values out of client-visible messages.

Audit logging (opt-in)

Set CUBRID_MCP_AUDIT_LOG=1 to record every executed statement (execute_query, explain_query, and execute_write) as a single structured JSON line on stderr. It is off by default and honoured per connection — a named connection sets CUBRID_<NAME>_MCP_AUDIT_LOG independently of the default. Each record is redaction-safe and contains only:

The raw SQL text, bound parameters, and literal values are never logged, so secrets embedded in a query (e.g. WHERE token = '...') do not reach the audit stream. Records go to stderr only and never to stdout.

Development

git clone https://github.com/cubrid-lab/cubrid-mcp-server.git
cd cubrid-mcp-server
python -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip   # the dev group needs pip >= 25.1
make install        # python -m pip install -e . --group dev
make doctor         # check the required tools

# Lint, format check & type check (ruff check ., ruff format --check ., mypy)
make check

# Unit tests with the 95% coverage floor (no database)
make test

# Integration tests on a run-owned Compose CUBRID that make starts and always removes
make integration    # CUBRID_VERSION=11.4 CUBRID_TEST_PORT=33000 by default

# Integration tests against a CUBRID you already run
export CUBRID_HOST=localhost CUBRID_USER=dba CUBRID_PASSWORD="" CUBRID_DATABASE=demodb
make integration-local

# A persistent local CUBRID (docker-compose.yml) for manual work; make integration never touches it
make docker-up      # demodb on 127.0.0.1:33000 (CUBRID_VERSION, CUBRID_TEST_PORT)
make docker-down    # keeps the data volume; make docker-clean deletes it

CI calls the same Make targets; make help lists them all and CONTRIBUTING.md describes each one.

The live shared-session concurrency regression can also be run on its own:

pytest tests/test_integration.py::TestCubridIntegration::test_concurrent_tool_calls_serialize_shared_session -q

It starts simultaneous in-process explain_query and execute_query calls on the same cached Database connection: the query must wait until the real trace context releases the existing RLock. It verifies independent responses, session reuse and cursor cleanup. This is not a test of MCP stdio transport concurrency, connection pooling or per-request transaction isolation.

Related Projects

• pycubrid — Pure-Python DB-API 2.0 driver this server is built on
• sqlalchemy-cubrid — SQLAlchemy 2.0–2.2 dialect for CUBRID
• cubrid-cookbook-python — 68 runnable examples incl. one-command app templates that use this stack

Disclaimer

This project is part of CUBRID Lab, an independent open-source initiative for CUBRID developer tooling, and is not affiliated with, sponsored by, or endorsed by CUBRID Corporation or the official CUBRID project.

License

MIT (see LICENSE).