🚀 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:

	Reaches	Therefore owns
MCP server (this repo)	Consumption and Catalog APIs	Reading data and metadata, catalog search, profiling
CLI	Design-time and admin APIs	Creating and changing objects, tenant administration

What each side does

Function	MCP	CLI
Read data rows	yes — `execute_query`, `smart_query`, `query_relational_entity`, `query_analytical_data`	no — no command returns table contents
Catalog search, asset lookup	`search_catalog`, `find_assets_by_column`, `get_asset_details`, …	—
Column profiling, distributions, outliers	`analyze_column_distribution`	—
Analytical/relational metadata (dimensions vs. measures, OData→SQL types)	`get_analytical_metadata`, `get_relational_metadata`	—
PII masking, SQL sanitizing, consent gating, audit logging	yes	—
Create/change/delete modeling objects (18 types)	local tables only (`create_table`)	yes
Spaces, users, global & scoped roles, workload, certificates	read-only or not at all	yes
Connections: create/change	read-only (`list_connections`, `test_connection`)	yes
Read an object definition (CSN)	—	`objects <type> read`
See deployed but non-exposed objects	via CLI (`list_repository_objects`)	`objects <type> list`
Task chains, task logs	`run_task_chain`, `get_task_log`, `get_task_status`, `get_task_history`	`tasks …`
Database users	`create_database_user`, …	`dbusers`

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:

CLI creates the layers — staging/cleansing/integration views, target tables, transformation flows, task chain, analytic model.
CLI runs the chain and reports task status.
MCP verifies the result: row counts, value distributions, whether data quality flags actually fire — everything the CLI structurally cannot see.
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.

Guide	Content
docs/MCP_VS_CLI.md	Authoritative capability split and routing rules
docs/TENANT_CONFIG.md	The three config files and the two identities
docs/CLI_LINEAGE_LOOKUP.md	Finding objects the Consumption API cannot see

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.

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

Tool	Purpose
`find_assets_by_column`	Which assets contain a given column — lineage and impact analysis across spaces
`analyze_column_distribution`	Null rate, distinct values, percentiles, IQR outlier detection

Querying data (4)

Tool	Purpose
`smart_query`	SQL router: picks analytical vs relational, falls back to client-side aggregation when the asset cannot aggregate
`execute_query`	SELECT over one entity (columns/`*`, WHERE, ORDER BY, LIMIT), max 1000 rows. JOIN / GROUP BY / aggregates are rejected with a pointer to the right tool
`query_relational_entity`	Relational OData, up to 50,000 records per batch for ETL
`query_analytical_data`	Analytical OData with `$apply`, `$filter`, `$orderby`

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)

Tool	Purpose
`list_repository_objects`	Lists design-time objects via the CLI, so it also sees objects not exposed for consumption
`get_deployed_objects`	Deployed objects in a space
`get_object_definition`	Object definition (deprecated — prefer `get_asset_details`)

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.

Environment variable	Values	Default	Purpose
`DATASPHERE_PII_POLICY`	path to YAML or JSON	(unset)	Policy file. Unset = masking fully disabled.
`DATASPHERE_PII_MODE`	`enforce` \| `audit_only` \| `off`	`enforce` when a policy is present	`audit_only` logs what would be masked without changing data
`DATASPHERE_PII_SALT`	secret string	(empty)	Salt for deterministic `hash`/`tokenize`. Treat as a secret.

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.

Flag	Env var	Default	Purpose
`--transport`	`MCP_TRANSPORT`	`stdio`	`stdio` or `http`
`--host`	`MCP_HTTP_HOST`	`127.0.0.1`	Bind address
`--port`	`MCP_HTTP_PORT`	`8080`	Bind port
`--path`	`MCP_HTTP_PATH`	`/mcp`	Endpoint path
`--auth-token`	`MCP_HTTP_AUTH_TOKEN`	(none)	Require `Authorization: Bearer <token>`

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

Guide	Content
Getting Started	Setup walkthrough with examples
API Reference	Technical API docs, Python and cURL
OAuth Setup	App Integration and OAuth client
Tenant Config	Config files, the two identities
MCP vs CLI	Which tool owns which task
CLI Lineage Lookup	Objects invisible to Consumption
Deployment	Docker, Kubernetes, PyPI
Developer Guide	Contributing to the codebase
Changelog	Version history

🙏 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

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.devcontainer		.devcontainer
bin		bin
docs		docs
examples		examples
src/sap_datasphere_mcp		src/sap_datasphere_mcp
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
.ruff.toml		.ruff.toml
.secrets.baseline		.secrets.baseline
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
pii_policy.yaml		pii_policy.yaml
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py
uv.lock		uv.lock

Navigation Menu

Repository files navigation

🚀 SAP Datasphere MCP Server

🤝 Relationship to the SAP Datasphere CLI

What each side does

How they combine in practice

🚀 Quick Start

Configuration

Claude Desktop

🛠️ Tool Catalog

Foundation (5)

Space discovery (3)

Catalog and search (5)

Data discovery and quality (2)

Querying data (4)

Metadata (7)

Repository (3)

Database users (5) — CLI-backed

Tasks (4)

Object provisioning (1) — CLI-backed

Operations (4)

🔏 PII / Sensitive-Field Masking

🔒 Security

🌐 Transports

📊 Architecture

🧪 Testing

🚀 Deployment

📚 Documentation

🙏 Acknowledgments

📄 License

📞 Support

About

Releases

Packages

Contributors

Languages

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

Folders and files

Latest commit

History

Repository files navigation

🚀 SAP Datasphere MCP Server

🤝 Relationship to the SAP Datasphere CLI

What each side does

How they combine in practice

🚀 Quick Start

Configuration

Claude Desktop

🛠️ Tool Catalog

Foundation (5)

Space discovery (3)

Catalog and search (5)

Data discovery and quality (2)

Querying data (4)

Metadata (7)

Repository (3)

Database users (5) — CLI-backed

Tasks (4)

Object provisioning (1) — CLI-backed

Operations (4)

🔏 PII / Sensitive-Field Masking

🔒 Security

🌐 Transports

📊 Architecture

🧪 Testing

🚀 Deployment

📚 Documentation

🙏 Acknowledgments

📄 License

📞 Support

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages