🚀 SAP Datasphere MCP Server

CLI + MCP are a combo. This repo owns consumption / catalog (read rows, search, profile). Its counterpart owns design-time / admin (create and change objects). Use them together — not as alternatives.

Half	Repository
MCP (this repo)	DimiDR/SAP-Datasphere-MCP
CLI	DimiDR/SAP-Datasphere-CLI

Model Context Protocol server that lets AI assistants explore and query SAP Datasphere — metadata discovery, catalog search, OData and SQL queries, ETL extraction, data lineage and column profiling — with built-in config-driven PII masking so sensitive fields never reach the LLM.

Version 1.4.0 · 42 tools advertised by default (51 with DATASPHERE_TOOL_PROFILE=full)

🙌 Shout-out: this repository is a modified copy of MarioDeFelipe/sap-datasphere-mcp. All credit for the original server goes to Mario de Felipe — this fork adapts it for a specific tenant setup and CLI integration.

🤝 Relationship to the SAP Datasphere CLI

This server and the @sap/datasphere-cli are complementary halves, not alternatives. They reach different API families, and nearly every difference follows from that:

What each side does

The CLI cannot read data rows — that is this server's reason to exist. This server does not create objects, apart from local tables (create_table), because the payload there is derived from data it has already read. Views, analytic models, flows, spaces, users and roles belong to the CLI.

Neither writes data rows. Rows arrive through a data/replication flow, a database user with a SQL client, or a CSV upload in the Data Builder UI. Neither manages folders — those are UI-only.

How they combine in practice

A typical build-then-verify loop:

1. CLI creates the layers — staging/cleansing/integration views, target tables, transformation flows, task chain, analytic model.

2. CLI runs the chain and reports task status.

3. MCP verifies the result: row counts, value distributions, whether data quality flags actually fire — everything the CLI structurally cannot see.

4. Findings flow back into step 1 as CSN changes.

Keep the visibility gap in mind: Consumption and Catalog endpoints only show objects that are deployed and exposed for consumption. A view that exists in the repository but is not exposed is invisible here while the CLI still sees it — that is what list_repository_objects exists for.

A few tools shell out to the CLI (create_table, the *_database_user* tools, list_repository_objects). The CLI keeps its own session, separate from this server's OAuth credentials — check it with the datasphere_cli_status tool.

Related MCP server: Semantic BI MCP

🚀 Quick Start

# npm
npm install -g @mariodefe/sap-datasphere-mcp && npx @mariodefe/sap-datasphere-mcp

# PyPI
pip install sap-datasphere-mcp && sap-datasphere-mcp

# From source
git clone https://github.com/MarioDeFelipe/sap-datasphere-mcp.git
cd sap-datasphere-mcp
pip install -r requirements.txt && pip install -e .
cp .env.example .env      # fill in your credentials
sap-datasphere-mcp

Full walkthrough: docs/GETTING_STARTED.md · OAuth setup: docs/OAUTH_SETUP.md

Configuration

DATASPHERE_BASE_URL=https://your-tenant.eu10.hcs.cloud.sap
DATASPHERE_TENANT_ID=your-tenant-id
DATASPHERE_CLIENT_ID=your-client-id
DATASPHERE_CLIENT_SECRET=your-client-secret
DATASPHERE_TOKEN_URL=https://your-tenant.authentication.eu10.hana.ondemand.com/oauth/token
USE_MOCK_DATA=false

Optional settings for the CLI-backed tools (DATASPHERE_CLI_PATH, _HOST, _SECRETS_FILE) are documented in .env.example and docs/TENANT_CONFIG.md.

Never commit .env.

Claude Desktop

{
  "mcpServers": {
    "sap-datasphere": {
      "command": "npx",
      "args": ["@mariodefe/sap-datasphere-mcp"],
      "env": {
        "DATASPHERE_BASE_URL": "https://your-tenant.eu20.hcs.cloud.sap",
        "DATASPHERE_CLIENT_ID": "your-client-id",
        "DATASPHERE_CLIENT_SECRET": "your-client-secret",
        "DATASPHERE_TOKEN_URL": "https://your-tenant.authentication.eu20.hana.ondemand.com/oauth/token"
      }
    }
  }
}

Config location — Windows: %APPDATA%\Claude\claude_desktop_config.json · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Linux: ~/.config/Claude/claude_desktop_config.json

🛠️ Tool Catalog

42 tools in the default lean profile. Set DATASPHERE_TOOL_PROFILE=full to also advertise overlapping metadata tools, and DATASPHERE_EXPOSE_DIAGNOSTICS=true for the endpoint probes — 51 in total. Hiding them by default improves the model's tool selection; every handler stays reachable.

Foundation (5)

test_connection · get_current_user · get_tenant_info · get_available_scopes · list_spaces

Space discovery (3)

get_space_info · get_table_schema · search_tables

Catalog and search (5)

list_catalog_assets · get_asset_details · get_asset_by_compound_key · get_space_assets · search_catalog

Catalog search runs client-side: /catalog/search returns 404 on the tenants tested, so these tools fetch assets and filter locally across name, label, businessName and description.

Data discovery and quality (2)

Querying data (4)

Supported SQL: SELECT */column lists, WHERE, LIMIT, GROUP BY, aggregations with and without grouping, ORDER BY. No JOINs — OData is single-entity. Names are case-sensitive.

Metadata (7)

get_relational_metadata · list_relational_entities · get_relational_entity_metadata · get_analytical_metadata · get_analytical_model · list_analytical_datasets · get_asset_variables

get_relational_entity_metadata maps OData types to SQL (Edm.String → NVARCHAR(MAX), Edm.Int64 → BIGINT, Edm.Decimal → DECIMAL(18,2), …) for data-warehouse loading. get_asset_variables surfaces input parameters a parameterised view or analytic model expects.

Repository (3)

Database users (5) — CLI-backed

list_database_users · create_database_user · update_database_user · delete_database_user · reset_database_user_password

High-risk operations require consent, cached for 60 minutes.

Tasks (4)

get_task_status · run_task_chain · get_task_log · get_task_history

Object provisioning (1) — CLI-backed

create_table — builds a CSN definition from your column list and runs datasphere objects local-tables create. Local tables only; see the CLI split above.

Operations (4)

list_connections · browse_marketplace · datasphere_cli_status · get_relational_odata_service (full profile)

datasphere_cli_status reports whether the CLI is installed, which version, which host, and whether a session exists. Run it first when a CLI-backed tool fails.

🔏 PII / Sensitive-Field Masking

A config-driven, fail-closed masking layer runs inside the response pipeline. Every data-returning tool (smart_query, query_relational_entity, query_analytical_data, get_space_assets, analyze_column_distribution) funnels results through apply_masking() before they reach the LLM. No prompt bypasses it.

Defense in depth. The authoritative access control stays upstream — SAP Datasphere Data Access Controls, and not granting the technical user access to PII tables. This layer is the enforced, auditable net on top.

If the policy file is configured but missing or unparseable, the server raises at startup and refuses to run. It never silently serves raw data with a broken policy.

mode: enforce
default_action: redact

rules:
  # Most specific wins: asset > space > global; exact > glob
  - space: ZDCS_08
    asset: ZR_SAP_CUSTOMER
    columns:
      EMAIL:  redact       # → "***"
      PHONE:  partial:4    # keep last 4 → "******1234"
      TAXID:  hash         # sha256(salt:value) — deterministic, safe for GROUP BY
      SSN:    drop         # column removed from every row
  - space: "*"
    columns:
      "*IBAN*": tokenize   # glob on column name → "TKN_<8hex>"

allowlist:
  enabled: true
  assets:
    ZDCS_08.ZR_OTC_CUST_MONTH: [CUSTOMER, MONTH, REVENUE]   # ONLY these returned

patterns:
  email: '[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}'
  iban:  '\b[A-Z]{2}\d{2}[A-Z0-9]{10,30}\b'

Precedence: allowlist (drops everything unlisted) → column rules → value-pattern scan on remaining strings.

Audit log — one structured line per call, values never logged:

[pii_masking] space=ZDCS_08 asset=ZR_SAP_CUSTOMER rows=42
              masked_fields=['EMAIL', 'PHONE', 'SSN'] mode=enforce

The response also carries masked_fields, so the client can see what was withheld. Annotated example: pii_policy.yaml.

🔒 Security

Authentication — OAuth 2.0 client credentials, tokens refreshed 60s before expiry and encrypted in memory (Fernet). No credentials in code.

Authorization — four permission levels (READ, WRITE, ADMIN, SENSITIVE), interactive consent for high-risk operations, full audit logging.

Query safety — the SQL sanitizer is fail-closed on SELECT: INSERT/UPDATE/DELETE/DROP and SQL comments are blocked, along with 15+ injection patterns. Write paths do not exist.

🌐 Transports

stdio by default; Streamable HTTP (spec 2025-03-26) at /mcp for long-lived service deployments.

pip install 'sap-datasphere-mcp[http]'
sap-datasphere-mcp --transport http --port 8080

The server warns when bound to a non-loopback interface without a token. /health serves a plain JSON liveness probe.

📊 Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │◄──►│   MCP Server     │◄──►│  SAP Datasphere │
│ (Claude, Cursor)│    │  Authorization   │    │   (OAuth 2.0)   │
│                 │    │  PII masking     │    │                 │
│                 │    │  Caching         │    │  datasphere CLI │
└─────────────────┘    └──────────────────┘    └─────────────────┘

src/sap_datasphere_mcp/
├── server.py              # MCP server and all tool handlers
├── cli_runner.py          # Single entry point for `datasphere` CLI calls
├── pii_masking.py         # Config-driven, fail-closed masking
├── cache_manager.py       # TTL cache
├── telemetry.py           # Request metrics
├── tool_descriptions.py   # Tool metadata
├── error_helpers.py       # Error formatting
├── auth/
│   ├── oauth_handler.py             # Token management and refresh
│   ├── datasphere_auth_connector.py # Authenticated API connector
│   ├── authorization.py             # Permission levels
│   ├── consent_manager.py           # Consent tracking
│   ├── input_validator.py           # Input validation
│   ├── sql_sanitizer.py             # SELECT-only enforcement
│   └── data_filter.py               # Credential redaction
└── config/settings.py     # Environment-based settings

Caching TTLs — spaces 1h · assets 30min · metadata 15min · users 5min, LRU eviction.

Response times — cached metadata under 100ms · catalog 100–500ms · OData queries 500–2000ms depending on volume.

🧪 Testing

pytest                                              # full suite
pytest tests/test_cli_runner.py                     # CLI integration layer
npx @modelcontextprotocol/inspector sap-datasphere-mcp

tests/test_cli_runner.py verifies every CLI command the server hardcodes against the --help dumps in the DataphereCLI repo. Point DATASPHERE_CLI_HELP_DIR at tools/cli-help to enable it; it skips otherwise.

Known failure: tests/test_mcp_server.py uses await server.list_resources()(), an idiom the current MCP SDK no longer supports. Pre-existing, unrelated to the server itself.

🚀 Deployment

docker build -t sap-datasphere-mcp:latest .
docker run -d --name sap-mcp --env-file .env sap-datasphere-mcp:latest
# or
docker-compose up -d

Full guide incl. Kubernetes: docs/DEPLOYMENT.md

📚 Documentation

🙏 Acknowledgments

This repository started as a modified copy of MarioDeFelipe/sap-datasphere-mcp. Shout-out to Mario de Felipe for the original server — the tool catalog, PII masking design and OAuth flow this fork builds on all trace back there.

Built with Amazon Kiro (specifications and architectural steering) and Claude Code (security and authentication, tool descriptions and error handling, caching and telemetry, repository and analytics tools, CLI integration layer).

📄 License

MIT — see LICENSE.

📞 Support

Issues · Discussions · SAP Datasphere docs · Model Context Protocol