OraViz MCP
OraViz MCP is a read-only, visualization-first MCP server for Oracle AI Database that lets you query, profile, and chart data.
execute_query – run read-only
SELECT/WITHqueries and get a compact markdown table with a metadata header and preview caps.list_tables – list tables and views in the current (or a specified) schema.
get_table_schema – get column names, types, length, nullability, and primary-key membership for a table/view.
sample_table_data – fetch a small sample of rows (default 10, configurable) from a table.
get_table_details – retrieve owner, tablespace, optimizer stats (e.g.,
NUM_ROWS,LAST_ANALYZED), and optionally an exact row count.profile_table – get per-column stats (non-null, distinct, min, max, avg) to decide which chart to use.
create_chart – run a read-only SQL query and render the result as a PNG chart (
bar,line,area,scatter,pie,histogram; README also describesvectorwith PCA), returning the image plus a short data preview.
All tools enforce read-only SQL, bounded result sizes, per-cell truncation, and context‑engineered output to keep agent token usage low.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OraViz MCP profile the sales table and show revenue by region as a bar chart"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OraViz MCP is pab1it0/adx-mcp-server reimagined for Oracle AI Database -- a
deliberately tiny alternative to the broad official Oracle MCP servers. It speaks SQL, profiles tables, and turns result
sets into PNG charts any MCP client can show. Seven read-oriented tools, no Oracle client libraries (python-oracledb
thin mode talks straight to Oracle AI Database 26ai Free or any newer release).
Two ideas shape everything:
Visualization first. The headline tool runs your query and returns an actual chart image plus a short data preview -- not a wall of rows.
Context engineering. Agents pay for every token a tool returns, so OraViz never dumps a result set. Results are preview-capped, rendered as one compact markdown table with a metadata header, and large values (CLOB, BLOB, VECTOR) are summarised. Raw LOBs are never read.
Deploy with a dedicated Oracle reader account. Network transports require verified bearer tokens; stdio uses local OS trust. See SECURITY.md for the security boundaries and deployment checklist.
Visualization at a Glance
Related MCP server: oradb-explorer-mcp
Why OraViz?
Charts, not query dumps --
create_chartrenders bar, line, area, scatter, pie, histogram, and vector (PCA) charts with an Oracle-red palette and returns the PNG as MCP image content.Context-engineered results -- bounded previews with explicit
truncatedmetadata, one header per table instead of repeated JSON keys, CLOB/BLOB/VECTOR summarised, per-cell truncation.Profile before you plot --
profile_tablereturns per-column nulls, distinct counts, min/max/avg so the model can pick the right chart without fetching rows.Conservative query admission -- one
SELECT/WITHwith a reviewed built-in function allowlist; unreviewed calls with parentheses, writes, PL/SQL, database links, sequences, and locking are denied. Bare parameterless routines and routines inside views/synonyms can escape lexical detection. OracleREADgrants and review of inherited/PUBLICexecution privileges are essential.ORACLE_CALL_TIMEOUTbounds each database round trip.Controlled surface -- 7 tools with an operator allowlist, strict inputs, bounded concurrency, authenticated network transports, and metadata-only JSON audit logs on stderr (stdout stays clean for stdio).
Zero client install -- python-oracledb thin mode; no Oracle Instant Client, no
ORACLE_HOME, no tnsnames.
The Context Contract
Every row-returning tool follows the same rules, and the test suite asserts them:
Rule | Default | Env knob |
Query preview size ( | 25 rows |
|
Hard row cap per query (charts included) | 500 rows |
|
Longest cell before | 500 chars |
|
Database round-trip timeout (not a whole-tool deadline) | 60 s; range 1–300, cannot disable |
|
Result columns | 64; maximum 200 |
|
Combined text + serialized JSON structured content / PNG limit | 256,000 characters / 2,000,000 bytes | Fixed |
Concurrent tool calls per process | 4; range 1–32 |
|
Metadata header per result |
| -- |
A tool result therefore looks like this instead of a 25-dictionary JSON array:
4 row(s) | columns: REGION, REVENUE
| REGION | REVENUE |
|---|---|
| East | 573932 |
| North | 502897 |
| South | 432190 |
| West | 360759 |Raw CLOB/NCLOB/BLOB/BFILE locators render as <LOB> without reading their contents; byte values are
summarized, VECTOR(384) renders as <VECTOR(384)>, and midnight timestamps as dates. For more rows, pass
max_rows explicitly -- and the server still stops at the hard cap.
Numeric settings have bounded defaults (at most 5,000 rows and 4,096 characters per cell). Invalid numeric environment settings warn and fall back to defaults. Over-limit MCP responses are rejected, including when a rendered table was already truncated but the combined response exceeds the budget. Data mirrored in text and structured JSON counts in both representations. Row/output caps do not bound database CPU or total execution time; see resource limits.
Tools
Tool | Returns | Context cost |
| Read-only SQL result as a compact markdown table (preview-capped) | Bounded by preview cap |
| Tables and views in the current (or a given) schema | One small table |
| Columns, types, length, nullability, primary-key membership | One small table |
| First rows of a table |
|
| Owner, tablespace, optimizer stats ( | Single row |
| Per-column stats: non-null, nulls, distinct, min, max, avg | ~1 line per column |
| PNG chart image + short data preview | Image + ≤5 preview rows |
How create_chart maps columns
The first column is the x-axis (or the labels for pie and vector charts); numeric columns after it become series. That makes the chart contract simple and SQL-driven:
SELECT region, ROUND(SUM(revenue), 2) AS revenue
FROM oraviz.sales_demo
GROUP BY region
ORDER BY revenue DESCcreate_chart(sql=..., chart_type="bar", title="Revenue by region")SELECT product_name, embedding FROM oraviz.product_vectorscreate_chart(sql=..., chart_type="vector", title="Product embeddings")bar/line/area-- label column plus one or more numeric series (up to 8 series; bar values are annotated when the chart is small)scatter-- first two numeric columnspie-- label column plus one numeric column; more than 12 slices are grouped into "Other"histogram-- the first numeric column, auto-binnedvector-- the first VECTOR column is projected to two dimensions with PCA (dense and sparse vectors both work); the first non-vector column labels the points, and each axis names the share of variance its component explains
Quick Start
1. Start Oracle AI Database 26ai Free
# Disposable local development database; the admin password is NOT the MCP password.
read -rsp 'Database admin password: ' ORAVIZ_DB_ADMIN_PASSWORD
export ORAVIZ_DB_ADMIN_PASSWORD
docker compose up -d
unset ORAVIZ_DB_ADMIN_PASSWORDThe container takes a couple of minutes to initialize. docker ps shows (healthy) when it is ready.
The listener is published only on 127.0.0.1:1530. The database stores data in a named volume.
The floating database image is for this demo; pin a reviewed digest for controlled deployments.
2. (Optional) Load the demo schema
Create an owner only for setup, then give a separate reader access to the two demo tables. The SQL below uses password placeholders: replace them privately with separate generated passwords. Do not reuse the legacy passwords or broad grants in the demo script's historical header.
docker exec -it oraviz-oracle sqlplus -L system@//localhost:1521/FREEPDB1At the SQL prompt (admin use is limited to provisioning):
CREATE USER oraviz IDENTIFIED BY "REPLACE_WITH_OWNER_SECRET"
DEFAULT TABLESPACE USERS QUOTA 20M ON USERS;
GRANT CREATE SESSION, CREATE TABLE TO oraviz;
CREATE USER oraviz_reader IDENTIFIED BY "REPLACE_WITH_READER_SECRET";
GRANT CREATE SESSION TO oraviz_reader;
EXIT;Load the deterministic 96-row SALES_DEMO and six-row PRODUCT_VECTORS tables as the owner.
The script drops and recreates these tables; use it only in this disposable schema.
docker cp examples/demo-sales.sql oraviz-oracle:/tmp/oraviz-demo-sales.sql
docker exec -it oraviz-oracle sqlplus -L oraviz@//localhost:1521/FREEPDB1At the owner SQL prompt:
@/tmp/oraviz-demo-sales.sql
GRANT READ ON oraviz.sales_demo TO oraviz_reader;
GRANT READ ON oraviz.product_vectors TO oraviz_reader;
EXIT;The initial DROP TABLE statements can report missing tables on a fresh schema.
Only ORAVIZ_READER is used by the MCP server. For production, grant READ on
approved tables or reviewed views and audit inherited permissions; never use a schema owner or admin.
3. Point your MCP client at the server
Replace REVIEWED_COMMIT_SHA with an audited commit ID. Inject ORACLE_PASSWORD into the MCP host's
protected process environment; it is intentionally absent from the shareable client configuration.
{
"mcpServers": {
"oraviz": {
"command": "uvx",
"args": ["--from", "git+https://github.com/jasperan/oraviz-mcp@REVIEWED_COMMIT_SHA", "oraviz-mcp"],
"env": {
"ORACLE_USER": "oraviz_reader",
"ORACLE_DSN": "localhost:1530/FREEPDB1"
}
}
}
}{
"mcpServers": {
"oraviz": {
"command": "uv",
"args": ["--directory", "/path/to/oraviz-mcp", "run", "oraviz-mcp"],
"env": {
"ORACLE_USER": "oraviz_reader",
"ORACLE_DSN": "localhost:1530/FREEPDB1"
}
}
}
}docker build -t oraviz-mcp .{
"mcpServers": {
"oraviz": {
"command": "docker",
"args": ["run", "--rm", "-i", "--network", "host",
"-e", "ORACLE_USER", "-e", "ORACLE_PASSWORD", "-e", "ORACLE_DSN",
"oraviz-mcp"],
"env": {
"ORACLE_USER": "oraviz_reader",
"ORACLE_DSN": "localhost:1530/FREEPDB1"
}
}
}
}--network host is a Linux local-demo convenience for reaching the loopback database.
For a deployment, use a dedicated private network and restrict egress as described in SECURITY.md.
Inject the reader password at runtime, and use a reviewed image digest when distributing the image.
4. Ask for a chart
"Profile ORAVIZ.SALES_DEMO, then chart total revenue by region from ORAVIZ.SALES_DEMO."
The model will call profile_table, pick a chart type, run create_chart, and you get a rendered image back.
Configuration
Variable | Description | Default |
| Dedicated reader with | -- |
| Password for the user (required) | -- |
| Database hostname |
|
| Listener port |
|
| Service name |
|
| Full EZConnect descriptor; overrides host/port/service | -- |
| Wallet config directory (Autonomous Database / mTLS) | -- |
| Wallet location | -- |
| Wallet password | -- |
| Preview size, 1–5,000, also capped by max rows |
|
| Hard row cap per query, 1–5,000 |
|
| Per-cell truncation limit, 1–4,096 |
|
| Result column cap, 1–200 |
|
| Admitted calls per process, 1–32 |
|
| Comma-separated exact names from the seven tools above; empty/unknown entries reject startup | All seven |
| TCP connect timeout, seconds |
|
| Per database round-trip timeout, seconds, 1–300; cannot disable |
|
|
|
|
| Bind host for network transports |
|
| Bind port for network transports |
|
| Required network JWT issuer, HTTPS URL | -- |
| Required network JWT resource audience | -- |
| Required network signing-key endpoint, HTTPS URL | -- |
| Required network scopes, space-separated (e.g. | -- |
| Optional public HTTPS base URL for discovery, excluding | -- |
|
|
|
| structlog level number |
|
Copy .env.template to .env with umask 077 -- the server loads it via python-dotenv.
Keep it untracked, never source it as shell code, and use process environment injection for literal
secrets containing ${...}. Existing process environment settings take precedence.
All network transports (http, sse, streamable-http) require auth, including loopback and proxy use.
Bearer tokens need a valid RS256 signature, issuer, audience, expiry, nonempty signed sub, applicable nbf, and required scopes.
All authenticated users share the configured Oracle principal; this is not per-user or multitenant data
authorization. TLS, private networking, gateway limits, audit retention, and host approval for sensitive
reads/exports remain deployment responsibilities. See the network configuration example.
Architecture
oraviz-mcp
src/oraviz_mcp/
server.py # FastMCP app, config, Oracle client, validation, the 7 tools
charts.py # pure matplotlib rendering (bar/line/area/scatter/pie/histogram/vector -> PNG bytes)
main.py # entry point: env validation, transport selection
tests/
test_config.py # config dataclasses + env parsing
test_validation.py # SQL guard, identifiers, formatting, result rendering
test_charts.py # every chart type + validation errors
test_server_tools.py # all tools against a scripted fake cursor
test_main.py # entry point
integration/ # live Oracle tests (skipped without ORAVIZ_TEST_DSN)
examples/demo-sales.sql
docs/testing.mdData flow: the MCP client calls a tool -> server.py validates (validate_query / validate_table_name) ->
python-oracledb thin connection -> rows are narrowed (fetch cap) -> either rendered as a compact table
(render_rows) or handed to charts.py -> the model receives text, or an image plus a short preview.
Development
uv sync --extra dev # install everything (matplotlib, fastmcp, oracledb, pytest)
uv run pytest # hermetic unit suite (~98% line coverage; the 90% gate is enforced)
uv run pytest -k chart # focus on one area
# Live tests create/drop scratch objects: use a separate disposable test owner,
# not the MCP reader. Inject ORAVIZ_TEST_PASSWORD privately before this command.
ORAVIZ_TEST_DSN=localhost:1530/FREEPDB1 \
ORAVIZ_TEST_USER=oraviz \
uv run pytest tests/integration -v --no-cov
docker build -t oraviz-mcp . # container build (multi-stage, non-root)See docs/testing.md and tests/README.md for the testing story.
OraViz vs. the official Oracle MCP servers
Oracle ships rich, general-purpose MCP servers -- SQLcl's built-in MCP server
(run-sql, connect, schema-information, ...), ORDS MCP,
the OCI Database Tools MCP, and the reference servers in
oracle/mcp. Use those when you need breadth: DDL, transactions, RAC, RAG pipelines.
OraViz is the opposite bet: seven tools, read-only SQL, and a hard focus on turning data into pictures without flooding the model's context. If you want the database operated, use the official servers. If you want the database seen, use this one.
Benchmarks
Historical snapshot: the numbers, paper PDFs, and figures below were captured before security hardening. They are retained unchanged and have not been recomputed for the current schemas or limits. Current guarantees and limitations are in SECURITY.md; see also paper/README.md.
We measured the tokens an agent must process to answer the same questions through OraViz and through the
official SQLcl MCP server,
against the same 26ai Free database (tiktoken cl100k_base: tool schemas plus every tool result):
Stage | OraViz | SQLcl MCP | Savings |
Tool schemas (read once per session) | 862 | 2,139 | 59.7% |
Schema discovery | 69 | 354 | 80.5% |
Full 96-row dump | 825 | 2,136 | 61.4% |
Whole workflow (5 questions) | 2,337 | 5,006 | 53.3% |
The 10-row sample step trades ~55% more framing tokens than raw CSV, and that overhead cannot grow with
the result size. Rendering the aggregate as a chart costs 123 text tokens plus the PNG image. Full
methodology, step-by-step numbers, and reproduction commands: benchmarks/. The full
write-up is in paper/paper.pdf, the results deck in slides/, and a
live showcase at jasperan.github.io/oraviz-mcp.
Credits
pab1it0/adx-mcp-server-- the project this mirrors, tool for tool, for OracleOracle AI Database 26ai Free -- the database and its container image
python-oracledb -- thin-mode driver, no client libraries required
FastMCP and the Model Context Protocol
License
MIT -- see LICENSE.
Available Tools
7 toolscreate_chartCreate ChartA
Runs a read-only SQL query and renders the result as a chart image (PNG). chart_type is one of: bar, line, area, scatter, pie, histogram. The first column is the x-axis or labels; numeric columns after it become series. Returns the image plus a data preview.
Inputs: sql (required), chart_type (required), title, x_label, +1 more.
execute_queryExecute QueryA
Executes a read-only SELECT/WITH query and returns a compact markdown table plus a metadata line (row count, and whether more rows exist). Results are preview-capped by default to protect the caller's context: aggregate in SQL and only pass max_rows when the raw rows are really needed. Large cell values are summarised.
Inputs: query (required), max_rows. Returns: result
get_table_detailsGet Table DetailsA
Retrieves table details: owner, tablespace, optimizer statistics (NUM_ROWS, BLOCKS, AVG_ROW_LEN, LAST_ANALYZED) and, optionally, an exact row count.
Inputs: table_name (required), exact_row_count. Returns: object
get_table_schemaGet Table SchemaA
Retrieves the schema of a table or view as a compact markdown table: column name, data type, length, nullability, and whether the column is part of the primary key.
Inputs: table_name (required). Returns: result
list_tablesList TablesA
Retrieves a list of all tables and views available in the configured Oracle schema as a compact markdown table. Optionally takes a schema name.
Inputs: schema. Returns: result
profile_tableProfile TableB
Profiles a table for visualization: row count plus per-column statistics (non-null count, distinct count, min, max, average) to decide which chart fits the data.
Inputs: table_name (required), columns, max_columns. Returns: object
sample_table_dataSample Table DataA
Retrieves a small sample of rows from the specified table as a compact markdown table. sample_size controls how many rows to return (default: 10, capped by the server).
Inputs: table_name (required), sample_size. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools target clearly distinct operations, but a few boundaries require careful reading: create_chart and execute_query both run SQL, and get_table_details and get_table_schema both describe table metadata. The descriptions clarify the outputs enough that an agent should usually pick correctly.
All tool names follow a consistent snake_case verb_noun pattern: execute_query, list_tables, get_table_schema, sample_table_data, get_table_details, profile_table, create_chart. The naming is predictable and uniform across the set.
Seven tools is well-scoped for an Oracle exploration and visualization server. Each tool serves a distinct discovery or charting purpose without unnecessary bloat or missing core functionality.
The server covers the full exploration-to-visualization workflow: listing objects, inspecting schema, sampling data, profiling columns, running queries, and creating charts. Minor gaps exist, such as no table DDL viewer or chart configuration options, but an agent can accomplish the intended tasks without dead ends.
Maintenance
Related MCP Connectors
Renders interactive Chart.js charts and dashboards inline in AI conversations.
Clean messy tabular data and render publication-ready PNG charts from your AI assistant.
Charts and dashboards as images for AI agents. No browser, same data same bytes. Local and free.
Renders interactive Chart.js charts and dashboards inline in AI conversations. Supports bar, line, area, pie, doughnut, scatter, and radar charts with multi-chart dashboard grids.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI applications to run SQL queries and retrieve results from Oracle Database.8-
- FlicenseNot gradedqualityDmaintenanceEnables read-only exploration of Oracle databases through natural language, providing schema inspection and safe bounded SQL query execution.-
- FlicenseNot gradedqualityBmaintenanceEnables AI chatbots to securely answer natural-language questions against Oracle databases by discovering metadata, generating and validating read-only SQL, executing with limits, masking sensitive data, and logging all activity.-
- FlicenseNot gradedqualityBmaintenanceEnables AI clients to securely interact with Oracle databases using natural-language prompts, translating requests into structured queries and returning results for AI-powered data access.-