cubrid-mcp-server

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

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.

Both return application/json. 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

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

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, EXPLAIN, and WITH statements. Multi-statement queries are rejected.

The SQL whitelist is defense-in-depth, not a security boundary. It is a non-validating parser-based guardrail against obvious mistakes. The real enforcement layer is the database itself: always run the server as a CUBRID user that has only SELECT grants on the tables the model may read. 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. CUBRID auto-commits DDL, which defeats the rollback guarantee, so it is excluded from write mode.
• 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 remains read-only regardless of the write-mode flag.
• 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
pip install -e ".[dev]"

# Lint & type check
ruff check .
mypy cubrid_mcp_server

# Unit tests
pytest -m "not integration"

# Integration tests (requires running CUBRID)
export CUBRID_HOST=localhost CUBRID_USER=dba CUBRID_PASSWORD="" CUBRID_DATABASE=demodb
pytest -m integration

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