mcp-saphana

MCP (Model Context Protocol) server for SAP HANA. Enables Claude and other MCP clients to query, explore, and bulk-export data from SAP HANA instances using the native hdbcli driver.

Features

• Schema & table discovery — list schemas, list tables/views, search across schemas

• Table introspection — column definitions, data types, nullability

• Data sampling — fetch sample rows for profiling

• Table statistics — row count, disk size, memory footprint (with privilege-aware fallback)

• Column profiling — min/max/null count/distinct count for any column

• Large volume export — chunked pagination via LIMIT/OFFSET for multi-million row exports

• Dual output formats — markdown (human-readable) and json (machine-readable)

• Privilege-safe — gracefully falls back when MONITORING privilege is absent

Related MCP server: mcp-database

Architecture

server.py                   # FastMCP server (single file)
├── Lifespan connection     # One persistent hdbcli connection per server lifetime
├── 9 MCP tools             # Schema/table/column/query/export operations
└── Shared helpers          # _get_conn, _cursor_to_rows, _handle_hana_error, _safe_json

Connection strategy

• Uses SAP HANA's native hdbcli driver (not JDBC/ODBC)

• Single persistent connection via FastMCP lifespan context

• Supports single-container, multi-tenant (system DB), and SAP HANA Cloud

• TLS/SSL configurable via env vars

Large volume strategy

saphana_chunked_export wraps the user's SQL in a subquery with LIMIT/OFFSET and returns one chunk at a time. The caller increments chunk_index until has_more is false.

chunk 0: SELECT * FROM (user_sql) AS __q__ LIMIT 1000 OFFSET 0
chunk 1: SELECT * FROM (user_sql) AS __q__ LIMIT 1000 OFFSET 1000
...

Setup

1. Install dependencies

pip install -e .
# or manually:
pip install mcp hdbcli pydantic python-dotenv

2. Configure credentials

cp .env.example .env
# Edit .env with your HANA connection details

HANA_HOST=your-hana-host.example.com
HANA_PORT=39015
HANA_USER=your_username
HANA_PASSWORD=your_password

# Optional — for HANA Cloud / multi-tenant:
HANA_DATABASE=
HANA_ENCRYPT=false
HANA_SSL_VALIDATE_CERTIFICATE=true

Port reference:

3. Run

python server.py

Tools

Claude Desktop / MCP Client Configuration

Add to your MCP client config (e.g., ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "saphana": {
      "command": "python",
      "args": ["/path/to/mcp_saphana/server.py"],
      "env": {
        "HANA_HOST": "your-host",
        "HANA_PORT": "39015",
        "HANA_USER": "your_user",
        "HANA_PASSWORD": "your_password"
      }
    }
  }
}

Or use a .env file and omit the env block (the server loads .env automatically).

Evaluations

evaluation.xml contains 10 read-only questions targeting stable SAP HANA system catalog objects. Run them with the MCP evaluation harness:

pip install anthropic
export ANTHROPIC_API_KEY=your_key

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a server.py \
  -e HANA_HOST=your-host \
  -e HANA_USER=your_user \
  -e HANA_PASSWORD=your_password \
  evaluation.xml

Note: Question 8 in evaluation.xml has a placeholder answer (FILL_IN_FROM_YOUR_INSTANCE). Fill it in by running:

SELECT COUNT(*) FROM SYS.TABLES WHERE SCHEMA_NAME = 'SYS'

Known Limitations / Future Work

• saphana_chunked_export uses OFFSET-based pagination — performance degrades at very high offsets on large tables. For extreme volumes, consider SAP HANA's native EXPORT statement or partition-key-based pagination.

• No write tools (INSERT/UPDATE/DELETE) — read-only by design. Add a saphana_execute_dml tool with explicit destructive annotations if needed.

• No connection pooling — single persistent connection per server instance. For high-concurrency deployments, switch transport to streamable_http and manage a pool in the lifespan context.

• Evaluation question answers tied to standard HANA 2.0 SPS06+ catalog structure. Verify on your specific version.

Project Status