MCP server for Oracle AI Database 26ai

Ask your Oracle data.
Get a compact table, a chart, and a token bill you can plan for.

OraViz is a minimal, visualization-first MCP server: seven tools, read-only SQL, and a context contract on every result — preview caps with honest truncation markers, cells bounded at 500 characters, and charts rendered as MCP image content. Benchmarked against the official SQLcl MCP server on the same Oracle 26ai Free container.

See the query, end to end Read the paper (PDF) Benchmarks

53.7%: fewer tokens for the five-question workflow, schemas included
844 vs 2,139: tokens of tool schemas, read once per session
123 tok + PNG: text cost of answering the comparison question with a chart

4 row(s) | columns: REGION, REVENUE

| REGION | REVENUE  |
|--------|----------|
| East   | 573932   |
| North  | 502897   |
| South  | 432190   |
| West   | 360759   |

context contract active · preview cap 25 rows · cells ≤ 500 chars

Bar chart titled 'Total revenue by region (12 months)' rendered by the create_chart tool from live Oracle data, East leading with 573,932. — Rendered by `create_chart` from the query below — returned as an image content block plus a short text preview.

01 — The demo

One query, end to end

Every step below is a real exchange between an MCP client and OraViz against an Oracle AI Database 26ai Free container: the SQL the agent wrote, the result it received, and the chart it rendered.

Ask in SQL

The agent composes one read-only statement. Validation rejects anything that is not a single SELECT or WITH, then the query runs inside a 60-second statement timeout.

SELECT region, SUM(revenue) AS total_revenue
FROM sales_demo
GROUP BY region
ORDER BY total_revenue DESC;

Read a bounded result

One metadata line, one header, four rows. The preview cap and cell limit mean the cost of this result is the same whether the table holds 96 rows or 96 million.

4 row(s) | columns: REGION, REVENUE

| REGION | REVENUE |
|--------|---------|
| East   | 573932  |
| North  | 502897  |
| South  | 432190  |
| West   | 360759  |

See the answer

create_chart runs the same query and returns the PNG as image content together with a five-row preview, so text-only clients still receive the essentials.

The same revenue query rendered as a bar chart: East 573,932; North 502,897; South 432,190; West 360,759.

02 — The measurements

53.7% fewer tokens than the official MCP server

Identical questions to OraViz and to the official Oracle SQLcl 26.1 MCP server (sql -mcp), same database, same data. Counted with tiktoken: tool schemas read once per session, plus every tool result needed to answer.

−53.7%

workflow tokens, schemas included — 2,319 vs 5,006. The savings concentrate where context would otherwise grow: tool schemas (−60.5%), schema discovery (−80.5%), and an unaggregated 96-row dump (−61.4%).

−80.5% listing schema objects: 69 vs 354 tokens
−61.4% full 96-row dump: 825 vs 2,136 tokens
−60.5% tool schemas: 844 vs 2,139 tokens
+55% ten-row sample framing — bounded by design, not by data
123 tok chart path: aggregate rendered to PNG, no SQLcl equivalent

Horizontal bar chart comparing tokens per question: OraViz wins list objects, loses describe, aggregate and sample slightly, and wins the 96-row dump by a wide margin. — Per-question tokens. Small result sets pay a bounded markdown framing premium; wide results and discovery win by large margins.

Grouped bar chart of the workflow budget: tool schemas 844 vs 2,139 tokens, tool results 2,319 vs 5,004, total 2,319 vs 5,006. — The workflow budget by stage. The full methodology, per-step numbers, and the harness live in benchmarks/.

03 — The surface

Seven tools, each with one job

Small schemas are a per-session cost every agent pays. OraViz keeps them short and pushes the aggregation to SQL, where the database already operates.

execute_query
One bounded SELECT/WITH statement, returned as a compact markdown table with truncation metadata.
markdown
profile_table
Per-column counts, distinct values, min/max and averages — enough to choose a chart without fetching rows.
dict
create_chart
Bar, line, area, scatter, pie, and histogram renderings returned as a PNG plus a short preview.
image
list_tables
Tables and views in the current schema, capped with an explicit truncation marker.
markdown
get_table_schema
Columns, types, nullability, and primary-key flags, escaped for safe markdown.
markdown
sample_table_data
The first rows of a table with a sample note — useful before writing an aggregate.
markdown
get_table_details
Tablespace and optimizer statistics, optionally with an exact row count.
dict

04 — Run it

Point any MCP client at it

Thin-mode python-oracledb means no Oracle client libraries to install. Works with Claude Code, Crush, Cursor, or any compliant client over stdio or HTTP.

Run the server

uvx --from git+https://github.com/jasperan/oraviz-mcp oraviz-mcp

Credentials come from ORACLE_USER, ORACLE_PASSWORD, and ORACLE_DSN (or host/port/service).

Register it with your client

{
  "mcpServers": {
    "oraviz": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jasperan/oraviz-mcp", "oraviz-mcp"],
      "env": {
        "ORACLE_USER": "oraviz",
        "ORACLE_PASSWORD": "your_password",
        "ORACLE_DSN": "localhost:1521/FREEPDB1"
      }
    }
  }
}

Docker image, demo schema, and the full environment reference live in the README. The paper is here (PDF), and the deck summarizing the results is in slides/.

Ask your Oracle data.Get a compact table, a chart, and a token bill you can plan for.