🚀 SAP Datasphere MCP Server

Production-ready Model Context Protocol (MCP) server that enables AI assistants to seamlessly interact with SAP Datasphere environments for real tenant data discovery, metadata exploration, analytics operations, ETL data extraction, database user management, data lineage analysis, and column-level data profiling.

🚀 Quick Start

Option 1: Install via npm (Recommended for Node.js/Claude Desktop)

# Install globally
npm install -g @mariodefe/sap-datasphere-mcp

# Run the server
npx @mariodefe/sap-datasphere-mcp

Option 2: Install via PyPI (Python)

# Install from PyPI
pip install sap-datasphere-mcp

# Run the server
sap-datasphere-mcp

See Getting Started Guide for complete setup instructions.

---

✨ What's New in v1.1.0

🌐 Streamable HTTP Transport — the server now speaks MCP over HTTP as well as stdio, so you can run it as a long-lived service (Docker, ECS, App Runner, behind a reverse proxy) and point multiple clients at the same instance.

Highlights

• ✅ New --transport http flag — serves MCP Streamable HTTP (spec 2025-03-26) at /mcp, replacing the legacy SSE dual-endpoint dance with a single HTTP route.
• ✅ Backward compatible — stdio is still the default; existing Claude Desktop / Claude Code configs keep working with zero changes.
• ✅ Optional bearer-token auth — enable via --auth-token or MCP_HTTP_AUTH_TOKEN. The server warns if bound to a non-loopback interface without one.
• ✅ /health endpoint — plain JSON liveness probe for load balancers and uptime checks.
• ✅ Fixed async entry point — new main_sync() wraps asyncio.run(main()) so the console script works reliably on macOS and Linux.

Usage

# stdio (default, unchanged)
sap-datasphere-mcp

# Streamable HTTP on http://127.0.0.1:8080/mcp
sap-datasphere-mcp --transport http --port 8080

# Exposed on LAN with bearer-token auth
MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \
  sap-datasphere-mcp --transport http --host 0.0.0.0 --port 8080

# Via env vars only (great for Docker / ECS)
MCP_TRANSPORT=http MCP_HTTP_PORT=8080 \
MCP_HTTP_AUTH_TOKEN=$MY_TOKEN \
  sap-datasphere-mcp

Install with HTTP extras

pip install 'sap-datasphere-mcp[http]'   # adds starlette + uvicorn
# or
uv tool install 'sap-datasphere-mcp[http]' --python 3.12

Client call example

curl -N -X POST http://127.0.0.1:8080/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-03-26",
                 "capabilities":{},
                 "clientInfo":{"name":"curl","version":"0"}}}'

CLI / env reference

Flag	Env var	Default	Purpose
--transport	MCP_TRANSPORT	stdio	stdio or http
--host	MCP_HTTP_HOST	127.0.0.1	Bind address in HTTP mode
--port	MCP_HTTP_PORT	8080	Bind port in HTTP mode
--path	MCP_HTTP_PATH	/mcp	URL path for the MCP endpoint
--auth-token	MCP_HTTP_AUTH_TOKEN	(none)	Require Authorization: Bearer <token>

See PR #31 for implementation details.

---

✨ What's New in v1.0.9

Enhanced Aggregation & Improved Logging - Production-ready smart query enhancements:

v1.0.9 - Smart Query Enhancements:

• ✅ Simple Aggregation Support - Queries like SELECT COUNT(*) FROM table now work correctly

  • Support for aggregations without GROUP BY (returns single row)
  • Enhanced regex to handle ORDER BY in GROUP BY queries
  • Both simple and grouped aggregations fully supported

• ✅ Enhanced Asset Detection - Multi-strategy search reduces false warnings

  • Exact name match + contains match for case-insensitive searches
  • Graceful fallback for catalog API limitations
  • Better handling of schema-prefixed views

• ✅ Improved Logging - Better user experience with clearer messages

  • Info emoji (ℹ️) instead of warning emoji (⚠️) for non-critical messages
  • More accurate descriptions ("not in catalog search" vs "not found")
  • Actionable suggestions only when queries likely to fail

v1.0.8 - Critical Hotfix:

• ✅ Fixed aggregation fallback bug - Client-side aggregation now works in both primary and fallback paths

v1.0.7 - Smart Query Production Enhancements:

• ✅ Client-side aggregation for GROUP BY queries
• ✅ Asset capability detection
• ✅ Fuzzy table name matching
• ✅ LIMIT pushdown optimization

Result: 45 tools with production-ready smart query engine supporting all SQL patterns

See CHANGELOG_v1.0.9.md for complete details.

---

📊 Current Status

🎉 45 TOOLS AVAILABLE - 44 with real data (98%) | Phases 1-5.1 Complete + Smart Query Engine

• ✅ 98% Real Data Integration - 44/45 tools accessing actual tenant data
• ✅ OAuth 2.0 Authentication - Enterprise-grade security with automatic token refresh
• ✅ 100% Foundation Tools - All authentication, connection, and user tools working perfectly
• ✅ 100% Catalog Tools - Complete asset discovery and metadata exploration
• ✅ 100% Search Tools - Client-side search workarounds for catalog and repository
• ✅ 100% Database User Management - All 5 tools using real SAP Datasphere CLI
• ✅ 100% ETL Tools - All 4 Phase 5.1 tools with enterprise-grade data extraction (up to 50K records)
• ✅ NEW: Data Lineage & Quality - Column search and distribution analysis tools
• 🟡 1 diagnostic tool - Endpoint testing utility (intentionally mock mode)

---

📚 Complete Documentation

New! Comprehensive production-ready documentation:

Guide	Description	Time to Read
📖 Getting Started Guide	10-minute quick start with examples	10 min
📋 Tools Catalog	Complete reference for all 44 tools	30 min
🔧 API Reference	Technical API docs with Python/cURL examples	45 min
🚀 Deployment Guide	Production deployment (Docker, K8s, PyPI)	20 min
🐛 Troubleshooting	Common issues and solutions	15 min

Quick Links:

• 🆕 What's New - Latest features and improvements
• ⚡ Quick Start - Get running in 5 minutes
• 📊 Query Examples - What data you can query and how
• 🛠️ All Tools - Complete tool list
• 🔒 Security - OAuth 2.0 and authorization

---

📊 Query Examples & Available Data

The server provides access to 37+ data assets including sales, products, HR, financial, and time dimension data. See QUERY_EXAMPLES.md for complete examples and documentation.

Available Data Assets

• Sales Data: Detailed orders and analytics (All For Bikes, eBike 100, etc.)
• Product Catalog: Forklifts ($7,900), Bikes ($288-$699), specifications
• HR Analytics: Headcount, job classifications, locations
• Financial Data: Transaction details and GL accounts
• Time Dimensions: Calendar data from 1900-present

Quick Examples

Sales orders (Relational):

query_relational_entity(
    space_id="SAP_CONTENT",
    asset_id="SAP_SC_SALES_V_SalesOrders",
    entity_name="SAP_SC_SALES_V_SalesOrders",
    select="SALESORDERID,COMPANYNAME,GROSSAMOUNT,CURRENCY",
    top=5
)

Product information (Relational):

query_relational_entity(
    space_id="SAP_CONTENT",
    asset_id="SAP_SC_FI_V_ProductsDim",
    entity_name="SAP_SC_FI_V_ProductsDim",
    select="PRODUCTID,MEDIUM_DESCR,PRICE,CURRENCY",
    top=5
)

Sales analytics (Analytical):

query_analytical_data(
    space_id="SAP_CONTENT",
    asset_id="SAP_SC_SALES_AM_SalesOrders",
    entity_set="SAP_SC_SALES_AM_SalesOrders",
    select="COMPANYNAME,GROSSAMOUNT",
    orderby="GROSSAMOUNT desc",
    top=8
)

Performance: 1-5 second response times, up to 50K records per batch.

See QUERY_EXAMPLES.md for 37+ data assets, 5 detailed examples, and best practices.

---

🌟 Key Highlights

• 🎯 45 MCP Tools: Comprehensive SAP Datasphere operations via Model Context Protocol
• 🔐 OAuth 2.0: Production-ready authentication with automatic token refresh
• ✅ Real Data Access: 44 tools (98%) accessing actual tenant data - spaces, assets, users, metadata
• 🚀 API Integration: 44 tools (98%) with real data integration via API and CLI
• 🧠 Smart Query Engine: Production-ready SQL support with client-side aggregation for all query types
• 🔍 Asset Discovery: 36+ real assets discovered (HR, Finance, Sales, Time dimensions)
• 📊 Data Querying: Execute OData queries and ETL extraction through natural language on real data
• 🧬 Data Lineage: Find assets by column name for impact analysis and lineage tracking
• 📈 Data Quality: Statistical column analysis with null rates, percentiles, and outlier detection
• 👥 User Management: Create, update, and manage database users with real API
• 🧠 AI Integration: Claude Desktop, Cursor IDE, and other MCP-compatible assistants
• 🏆 100% Foundation & Catalog Tools: All core discovery tools fully functional
• 📦 Production Ready: Docker, Kubernetes, PyPI packaging available

---

🛠️ Complete Tool Catalog (45 Tools)

🏆 Real Data Success Summary

Category	Total Tools	Real Data	Success Rate
Foundation Tools	5	5 ✅	100%
Catalog Tools	4	4 ✅	100%
Space Discovery	3	3 ✅	100%
Search Tools	2	2 ✅	100% (client-side workarounds)
Data Discovery & Quality	2	2 ✅	100% (v1.0.3 - lineage & profiling)
Database User Management	5	5 ✅	100% (SAP CLI integration)
Metadata Tools	4	4 ✅	100%
Analytical Consumption Tools	4	4 ✅	100% (OData analytical queries)
Additional Tools	5	5 ✅	100% (connections, tasks, marketplace, etc.)
Relational Query Tool	1	1 ✅	100% (SQL to OData conversion)
Smart Query Engine	1	1 ✅	100% (v1.0.9 - all SQL patterns supported)
ETL-Optimized Relational Tools	4	4 ✅	100% (Phase 5.1 - up to 50K records)
Diagnostic Tools	3	0 🟡	Mock Mode (endpoint testing utilities)
Repository Tools (legacy)	2	0 ❌	0% (deprecated - use Catalog instead)
TOTAL	45	44 (98%)	98% Coverage

---

🔐 Foundation Tools (5 tools) - 100% Real Data ✅

Tool	Status	Description
test_connection	✅ Real Data	Test OAuth connection and get health status
get_current_user	✅ Real Data	Get authenticated user information from JWT token
get_tenant_info	✅ Real Data	Get SAP Datasphere tenant configuration
get_available_scopes	✅ Real Data	List OAuth2 scopes from token
list_spaces	✅ Real Data	List all accessible spaces (DEVAULT_SPACE, SAP_CONTENT)

Example queries:

"Test the connection to SAP Datasphere"
"Who am I? Show my user information"
"What tenant am I connected to?"
"What OAuth scopes do I have?"
"List all SAP Datasphere spaces"

Real Data Examples:

• Real tenant: your-tenant.eu20.hcs.cloud.sap
• Real spaces: DEVAULT_SPACE, SAP_CONTENT
• Real user info from OAuth JWT token
• Real OAuth scopes (typically 3+ scopes)

---

🔍 Space Discovery Tools (3 tools) - 100% Real Data ✅

Tool	Status	Description
get_space_info	✅ Real Data	Get detailed information about a specific space
get_table_schema	✅ Real Data	Get column definitions and data types for tables
search_tables	✅ Real Data	Search for tables and views by keyword (client-side filtering)

Example queries:

"Show me details about the SAP_CONTENT space"
"Get the schema for FINANCIAL_TRANSACTIONS table"
"Search for tables containing 'customer'"

Real Data Examples:

• Real space metadata from API
• Real table schemas (when tables exist in space)
• search_tables uses client-side filtering workaround (API doesn't support OData filters)

---

📦 Catalog & Asset Tools (4 tools) - 100% Real Data ✅

Tool	Status	Description
list_catalog_assets	✅ Real Data	Browse all catalog assets across spaces (36+ assets found!)
get_asset_details	✅ Real Data	Get comprehensive asset metadata and schema
get_asset_by_compound_key	✅ Real Data	Retrieve asset by space and name
get_space_assets	✅ Real Data	List all assets within a specific space

Example queries:

"List all catalog assets in the system"
"Get details for asset SAP_SC_FI_AM_FINTRANSACTIONS"
"Show me all assets in the SAP_CONTENT space"
"Get asset by compound key: space=SAP_CONTENT, id=SAP_SC_HR_V_Divisions"

Real Assets Discovered (36+ real assets):

• HR Assets: SAP_SC_HR_V_Divisions, SAP_SC_HR_V_JobClass, SAP_SC_HR_V_Location, SAP_SC_HR_V_Job
• Finance Assets: SAP_SC_FI_V_ProductsDim, SAP_SC_FI_AM_FINTRANSACTIONS
• Time & Sales Models: Multiple analytical models with real metadata URLs
• All assets include real metadata URLs pointing to your tenant

---

🔎 Search Tools (2 tools) - 100% Real Data ✅

Tool	Status	Description
search_catalog	✅ Real Data	Search catalog assets by query (client-side workaround)
search_repository	✅ Real Data	Search repository objects with filters (client-side workaround)

Example queries:

"Search catalog for 'sales'"
"Find repository objects containing 'customer'"
"Search for analytical models in SAP_CONTENT"

Real Data Examples:

• Client-side search across name, label, businessName, and description fields
• Support for facets (objectType, spaceId aggregation)
• Support for filters (object_types, space_id)
• Support for why_found tracking (shows which fields matched)
• Pagination and total_matches reporting

Implementation: Both tools use client-side search workarounds since /api/v1/datasphere/consumption/catalog/search endpoint returns 404 Not Found. They fetch all assets from /catalog/assets and filter client-side.

---

🔬 Data Discovery & Quality Tools (2 tools) - 100% Real Data ✅

Tool	Status	Description
find_assets_by_column	✅ Real Data	Find all assets containing a specific column name for data lineage
analyze_column_distribution	✅ Real Data	Statistical analysis of column data distribution and quality profiling

Example queries:

"Which tables contain CUSTOMER_ID column?"
"Find all assets with SALES_AMOUNT"
"Analyze the distribution of ORDER_TOTAL column"
"What's the data quality of CUSTOMER_AGE field?"
"Profile the PRICE column for outliers"

Real Data Examples:

• Data Lineage: Cross-space column search, impact analysis before schema changes
• Quality Profiling: Null rates, distinct values, percentiles, outlier detection (IQR method)
• Use Cases: Data discovery, schema relationship mapping, data quality assessment, pre-analytics profiling

Implementation: Both tools introduced in v1.0.3 provide advanced data discovery and quality capabilities:

• find_assets_by_column: Searches across multiple spaces, case-insensitive by default, up to 200 results
• analyze_column_distribution: Analyzes up to 10,000 records, automatic type detection, percentile analysis

---

📊 Metadata Tools (4 tools) - 100% Real Data ✅

Tool	Status	Description
get_catalog_metadata	✅ Real Data	Retrieve CSDL metadata schema for catalog service
get_analytical_metadata	✅ Real Data	Get analytical model metadata with pre-flight checks
get_relational_metadata	✅ Real Data	Get relational schema with SQL type mappings
list_analytical_datasets	✅ Real Data	List analytical datasets (fixed query parameters)

Example queries:

"Get the catalog metadata schema"
"Retrieve analytical metadata for SAP_SC_FI_AM_FINTRANSACTIONS"
"Get relational schema for CUSTOMER_DATA table"
"List analytical datasets"

Status: All 4 tools return real data with proper error handling and capability checks.

---

👥 Database User Management Tools (5 tools) - 100% Real Data ✅

Tool	Status	Description	Requires Consent
list_database_users	✅ Real Data	List all database users (SAP CLI)	No
create_database_user	✅ Real Data	Create new database user (SAP CLI)	Yes (ADMIN)
update_database_user	✅ Real Data	Update user permissions (SAP CLI)	Yes (ADMIN)
delete_database_user	✅ Real Data	Delete database user (SAP CLI)	Yes (ADMIN)
reset_database_user_password	✅ Real Data	Reset user password (SAP CLI)	Yes (SENSITIVE)

Example queries:

"List all database users in SAP_CONTENT space"
"Create a new database user named ETL_USER"
"Update permissions for DB_USER_001"
"Delete database user TEST_USER"
"Reset password for DB_USER_001"

Status: All 5 tools use real SAP Datasphere CLI integration with subprocess execution, temporary file handling, and comprehensive error handling.

Consent Management: High-risk operations (create, update, delete, reset password) require user consent on first use. Consent is cached for 60 minutes.

---

🔧 API Syntax Fixes (4 tools) - 100% Real Data ✅

Tool	Status	Description
search_tables	✅ Real Data	Search tables/views (client-side filtering)
get_deployed_objects	✅ Real Data	List deployed objects (removed unsupported filters)
list_analytical_datasets	✅ Real Data	List datasets (fixed query parameters)
get_analytical_metadata	✅ Real Data	Get metadata (pre-flight capability checks)

Status: All 4 tools fixed during Phase 2 - removed unsupported OData filters and added client-side workarounds.

---

🔧 HTML Response Fixes (2 tools) - 100% Real Data ✅

Tool	Status	Description
get_task_status	✅ Real Data	Graceful error handling for HTML responses
browse_marketplace	✅ Real Data	Professional degradation for UI-only endpoints

Status: Both tools fixed during Phase 3 - added content-type validation and helpful error messages when endpoints return HTML instead of JSON.

---

📈 Analytical Consumption Tools (4 tools) - 100% Real Data ✅

Tool	Status	Description
get_analytical_model	✅ Real Data	Get OData service document and analytical model metadata
get_analytical_service_document	✅ Real Data	Get service capabilities, entity sets, and navigation properties
list_analytical_datasets	✅ Real Data	List all analytical datasets and entity sets for a model
query_analytical_data	✅ Real Data	Execute OData analytical queries with $select, $filter, $apply, $top

Example queries:

"Get analytical model for SAP_SC_FI_AM_FINTRANSACTIONS"
"Show me the service document for SAP_SC_HR_V_Divisions"
"List all datasets in the analytical model"
"Query analytical data from SAP_SC_FI_AM_FINTRANSACTIONS with filters"

Real Data Features:

• OData v4.0 analytical consumption API (/api/v1/datasphere/consumption/analytical)
• Full metadata discovery (service documents, entity sets, properties)
• Advanced filtering with $filter, $select, $top, $skip, $orderby
• Aggregation support with $apply (groupby, aggregate functions)
• Real tenant data from your SAP Datasphere instance

Status: All 4 analytical consumption tools fully operational with real SAP Datasphere data!

---

🔌 Additional Tools (5 tools) - 100% Real Data ✅

Tool	Status	Description
list_connections	✅ Real Data	List all configured connections (HANA, S/4HANA, etc.)
get_task_status	✅ Real Data	Monitor task execution status and progress
browse_marketplace	✅ Real Data	Browse Data Marketplace assets and packages
get_consumption_metadata	✅ Real Data	Get consumption layer metadata (CSDL schema)
get_deployed_objects	✅ Real Data	List all deployed objects in a space

Example queries:

"List all connections in the system"
"Check the status of task 12345"
"Browse the Data Marketplace"
"Get consumption metadata schema"
"Show deployed objects in SAP_CONTENT"

Status: All additional tools provide essential system management capabilities with full real data support.

---

🧪 Diagnostic Tools (3 tools) - Endpoint Testing Utilities

Tool	Status	Description
test_analytical_endpoints	🧪 Diagnostic	Test analytical/query API endpoint availability
test_phase67_endpoints	🧪 Diagnostic	Test Phase 6 & 7 endpoint availability (KPI, monitoring, users)
test_phase8_endpoints	🧪 Diagnostic	Test Phase 8 endpoint availability (data sharing, AI features)

Purpose: These diagnostic tools help verify which SAP Datasphere API endpoints are available in your specific tenant configuration. They return structured reports with:

• HTTP status codes for each endpoint
• Error messages and troubleshooting guidance
• Recommendations for workarounds or alternative tools

Status: Diagnostic tools intentionally use mock/test mode to validate endpoint availability without modifying data.

---

🗂️ Repository Tools (2 tools) - Deprecated (Use Catalog Instead)

Tool	Status	Description
list_repository_objects	⚠️ Deprecated	List repository objects (use list_catalog_assets instead)
get_object_definition	⚠️ Deprecated	Get object definition (use get_asset_details instead)

Recommendation: These legacy repository tools are deprecated. Use the modern Catalog Tools instead:

• Replace list_repository_objects → list_catalog_assets or search_catalog
• Replace get_object_definition → get_asset_details

Status: Catalog Tools provide superior functionality with full real data support.

---

🔐 Relational Query Tool (1 tool) - 100% Real Data ✅

Tool	Status	Description	Requires Consent
execute_query	✅ Real Data	Execute SQL queries on Datasphere tables/views with SQL→OData conversion	Yes (WRITE)

Example queries:

"Execute query: SELECT * FROM SAP_SC_FI_AM_FINTRANSACTIONS LIMIT 10"
"Query: SELECT customer_id, amount FROM SALES_ORDERS WHERE status = 'COMPLETED' LIMIT 50"
"Get data: SELECT * FROM SAP_SC_HR_V_Divisions"

Real Data Features:

• SQL to OData Conversion: Automatically converts SQL queries to OData API calls
• Relational Consumption API: /api/v1/datasphere/consumption/relational/{space_id}/{view_name}
• Supported SQL Syntax:
  • SELECT * or SELECT column1, column2 → OData $select
  • WHERE conditions → OData $filter (basic conversion)
  • LIMIT N → OData $top
• Query Safety: Max 1000 rows, 60-second timeout
• Error Handling: Helpful messages for table not found, parse errors, permission issues

SQL Conversion Examples:

SELECT * FROM CUSTOMERS WHERE country = 'USA' LIMIT 10
→ GET /relational/SPACE/CUSTOMERS?$filter=country eq 'USA'&$top=10

SELECT customer_id, name FROM ORDERS LIMIT 20
→ GET /relational/SPACE/ORDERS?$select=customer_id,name&$top=20

Limitations:

• No JOINs (OData single-table queries only)
• Basic WHERE clause conversion (simple comparisons work)
• No GROUP BY, ORDER BY (future enhancement)
• Table/view names are case-sensitive

Status: ✅ Fully functional with real SAP Datasphere data! Tested and confirmed working.

---

🧠 Smart Query Engine (1 tool) - 100% Real Data ✅ NEW v1.0.9!

Tool	Status	Description	Requires Consent
smart_query	✅ Real Data	Intelligent SQL query router with client-side aggregation and multi-tier fallback	No (READ)

Example queries:

"Query: SELECT * FROM SAP_SC_FI_V_ProductsDim LIMIT 5"
"Get product counts by category: SELECT PRODUCTCATEGORYID, COUNT(*) FROM SAP_SC_FI_V_ProductsDim GROUP BY PRODUCTCATEGORYID"
"Simple aggregation: SELECT COUNT(*), AVG(PRICE) FROM SAP_SC_FI_V_ProductsDim"
"Analytics with sorting: SELECT CATEGORY, COUNT(*), AVG(PRICE) FROM Products GROUP BY CATEGORY ORDER BY COUNT(*) DESC"

Real Data Features:

• Intelligent Routing: Automatically chooses between analytical and relational endpoints based on query type and asset capabilities
• Client-Side Aggregation: Full support for SQL aggregations when API doesn't support them
  • Simple aggregations: SELECT COUNT(*) FROM table (returns single row)
  • GROUP BY aggregations: SELECT category, COUNT(*) FROM table GROUP BY category
  • All aggregate functions: COUNT, SUM, AVG, MIN, MAX
• Asset Capability Detection: Multi-strategy search to verify asset support before query execution
• Enhanced Error Messages: Fuzzy table name matching with actionable suggestions
• LIMIT Pushdown: Automatically converts SQL LIMIT to OData $top for optimal performance
• Multi-Tier Fallback: Primary (analytical) → Fallback (relational + aggregation) → Helpful error

Query Types Supported:

-- Simple queries
SELECT * FROM table LIMIT 10

-- Simple aggregations (NEW in v1.0.9)
SELECT COUNT(*) FROM table
SELECT COUNT(*), AVG(price), MAX(price) FROM table

-- GROUP BY aggregations
SELECT category, COUNT(*), AVG(price) FROM table GROUP BY category

-- Complex queries with ORDER BY
SELECT category, COUNT(*) as cnt FROM table GROUP BY category ORDER BY cnt DESC LIMIT 5

Performance:

• Response Times: 500ms - 2s depending on data volume
• Batch Size: Up to 50,000 records per query
• Optimization: LIMIT pushdown reduces data transfer by up to 95%

Status: ✅ Production-ready with comprehensive SQL support! All common query patterns working flawlessly (v1.0.7-v1.0.9 enhancements).

---

🏭 ETL-Optimized Relational Tools (4 tools) - 100% Real Data ✅ NEW Phase 5.1!

Tool	Status	Description	Requires Consent
list_relational_entities	✅ Real Data	List all available relational entities (tables/views) within an asset for ETL operations	No (READ)
get_relational_entity_metadata	✅ Real Data	Get entity metadata with SQL type mappings (OData→SQL) for data warehouse loading	No (READ)
query_relational_entity	✅ Real Data	Execute OData queries with large batch processing (up to 50,000 records) for ETL extraction	No (READ)
get_relational_odata_service	✅ Real Data	Get OData service document with ETL planning capabilities and query optimization guidance	No (READ)

Example queries:

"List all relational entities in SAP_CONTENT space for asset SAP_SC_SALES_V_Fact_Sales"
"Get entity metadata with SQL types for SAP_CONTENT/SAP_SC_SALES_V_Fact_Sales"
"Query relational entity from SAP_CONTENT, asset SAP_SC_SALES_V_Fact_Sales, entity Results, limit 1000"
"Get OData service document for SAP_CONTENT/SAP_SC_SALES_V_Fact_Sales with ETL capabilities"

Real Data Features:

• Large Batch Processing: Extract up to 50,000 records per query (vs 1,000 for execute_query)
• SQL Type Mapping: Automatic OData to SQL type conversion (NVARCHAR, BIGINT, DECIMAL, DATE, etc.)
• ETL Planning: Service discovery, entity enumeration, batch size recommendations
• Performance Optimization: Incremental extraction, parallel loading, pagination strategies
• Production Quality: Sub-second response times with real production data

ETL Use Cases:

• Data Warehouse Loading: Extract large datasets with proper SQL types for target databases
• Incremental Extraction: Use $filter with date columns for delta loads
• Parallel Extraction: Use $skip with multiple concurrent requests for high-volume data
• Schema Discovery: Get complete metadata with column types, precision, scale before ETL jobs

Advanced Query Capabilities:

OData Parameters Supported:
- $filter: Complex filtering expressions (e.g., "amount gt 1000 and status eq 'ACTIVE'")
- $select: Column projection (e.g., "customer_id,amount,date")
- $top/$skip: Pagination (up to 50K per batch)
- $orderby: Sorting (e.g., "amount desc, date asc")

SQL Type Mapping Examples:

Edm.String       → NVARCHAR(MAX)
Edm.Int32        → INT
Edm.Int64        → BIGINT
Edm.Decimal      → DECIMAL(18,2)
Edm.Double       → DOUBLE
Edm.Date         → DATE
Edm.DateTime     → TIMESTAMP
Edm.Boolean      → BOOLEAN

Endpoint Pattern:

GET /api/v1/datasphere/consumption/relational/{space}/{asset}               → List entities
GET /api/v1/datasphere/consumption/relational/{space}/{asset}/$metadata     → Get metadata
GET /api/v1/datasphere/consumption/relational/{space}/{asset}/{entity}      → Query data

Status: ✅ All 4 tools fully functional with enterprise-grade ETL capabilities! Tested with real production sales data, achieving sub-second performance with large result sets.

---

🚀 Quick Start

Prerequisites

Python 3.10+
SAP Datasphere account with OAuth 2.0 configured
Technical User with appropriate permissions

Installation

# 1. Clone the repository
git clone https://github.com/MarioDeFelipe/sap-datasphere-mcp.git
cd sap-datasphere-mcp

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure OAuth credentials
cp .env.example .env
# Edit .env with your SAP Datasphere OAuth credentials

# 4. Start MCP Server
python sap_datasphere_mcp_server.py

Configuration

Create a .env file with your SAP Datasphere credentials:

# SAP Datasphere Connection
DATASPHERE_BASE_URL=https://your-tenant.eu10.hcs.cloud.sap
DATASPHERE_TENANT_ID=your-tenant-id

# OAuth 2.0 Credentials (Technical User)
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

# Optional: Mock Data Mode (for testing without real credentials)
USE_MOCK_DATA=false

⚠️ Important: Never commit your .env file to version control!

📖 Need help with OAuth setup? See the complete guide: OAuth Setup Guide

---

🤖 AI Assistant Integration

Claude Desktop

Option 1: Using npm (Recommended)

Add to your claude_desktop_config.json:

{
  "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"
      }
    }
  }
}

Option 2: Using Python directly

{
  "mcpServers": {
    "sap-datasphere": {
      "command": "python",
      "args": ["-m", "sap_datasphere_mcp_server"],
      "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"
      }
    }
  }
}

Location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Example Natural Language Queries

Once configured, ask your AI assistant:

Space & Discovery:

"List all SAP Datasphere spaces"
"Show me the schema for the CUSTOMERS table"
"Search for tables containing 'sales' in SAP_CONTENT"

Metadata Exploration:

"Get the analytical metadata for REVENUE_ANALYSIS"
"Show me the catalog metadata schema"
"Get relational schema for FINANCIAL_TRANSACTIONS"

Analytical Queries:

"Query financial data where Amount > 1000"
"Get analytical model for SALES_ANALYTICS.REVENUE_ANALYSIS"
"Execute aggregation: group by Currency and sum Amount"

User Management:

"List all database users"
"Create a new database user named ETL_READER"
"Update permissions for user DB_USER_001"

Repository Objects:

"Get the complete definition for SAP_SC_FI_AM_FINTRANSACTIONS"
"Show me all assets in SAP_CONTENT space"
"Get repository search metadata"

---

🔒 Security Features

OAuth 2.0 Authentication

• ✅ Client Credentials Flow: Secure Technical User authentication
• ✅ Automatic Token Refresh: Tokens refreshed 60 seconds before expiration
• ✅ Encrypted Storage: Tokens encrypted in memory using Fernet encryption
• ✅ No Credentials in Code: All secrets loaded from environment variables
• ✅ Retry Logic: Exponential backoff for transient failures

Authorization & Consent

• ✅ Permission Levels: READ, WRITE, ADMIN, SENSITIVE
• ✅ User Consent: Interactive prompts for high-risk operations
• ✅ Audit Logging: Complete operation audit trails
• ✅ Input Validation: SQL injection prevention with 15+ attack patterns
• ✅ Data Filtering: Automatic PII and credential redaction

Security Best Practices

• 🔐 Environment-based Configuration: No hardcoded credentials
• 🔒 HTTPS/TLS: All communications encrypted
• 📝 Comprehensive Logging: Detailed security audit trails
• 🔑 Token Management: Automatic refresh and secure rotation
• 🛡️ SQL Sanitization: Read-only queries, injection prevention

---

📊 Architecture

System Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │◄──►│   MCP Server     │◄──►│  SAP Datasphere │
│ (Claude, Cursor)│    │  32 Tools        │    │   (OAuth 2.0)   │
│                 │    │  Authorization   │    │                 │
│                 │    │  Caching         │    │                 │
│                 │    │  Telemetry       │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Core Components

Authentication Layer:

• auth/oauth_handler.py - Token management and refresh
• auth/datasphere_auth_connector.py - Authenticated API connector
• auth/authorization.py - Permission-based authorization
• auth/consent_manager.py - User consent tracking

Security Layer:

• auth/input_validator.py - Input validation framework
• auth/sql_sanitizer.py - SQL injection prevention
• auth/data_filter.py - PII and credential redaction

Performance Layer:

• cache_manager.py - Intelligent caching with TTL
• telemetry.py - Request tracking and metrics

MCP Server:

• sap_datasphere_mcp_server.py - Main server with 42 tools

---

🚀 Production Deployment

Quick Deployment Options

Docker (Recommended):

# Build and run
docker build -t sap-datasphere-mcp:latest .
docker run -d --name sap-mcp --env-file .env sap-datasphere-mcp:latest

# Using Docker Compose
docker-compose up -d

PyPI Package (Coming Soon):

pip install sap-datasphere-mcp
sap-datasphere-mcp

Kubernetes:

# Create secrets
kubectl create secret generic sap-mcp-secrets \
  --from-literal=DATASPHERE_CLIENT_ID='...' \
  --from-literal=DATASPHERE_CLIENT_SECRET='...'

# Deploy
kubectl apply -f k8s/deployment.yaml
kubectl scale deployment sap-mcp-server --replicas=5

Manual:

git clone https://github.com/MarioDeFelipe/sap-datasphere-mcp.git
cd sap-datasphere-mcp
pip install -r requirements.txt
cp .env.example .env  # Edit with your credentials
python sap_datasphere_mcp_server.py

📖 See DEPLOYMENT.md for complete production deployment guide

---

📈 Performance Characteristics

Response Times

• ⚡ Metadata Queries: Sub-100ms (cached)
• ⚡ Catalog Queries: 100-500ms
• ⚡ OData Queries: 500-2000ms (depends on data volume)
• ⚡ Token Refresh: Automatic, transparent to user

Caching Strategy

• 📊 Spaces: 1 hour TTL
• 📦 Assets: 30 minutes TTL
• 🔍 Metadata: 15 minutes TTL
• 👥 Users: 5 minutes TTL
• 🔄 LRU Eviction: Automatic cleanup of old entries

Scalability

• 🔄 Concurrent Requests: Multiple simultaneous MCP operations
• 🛡️ Error Recovery: Automatic retry with exponential backoff
• 📊 Connection Pooling: Efficient resource management

---

🧪 Testing

Run Tests

# Test MCP server startup
python test_mcp_server_startup.py

# Test authorization coverage
python test_authorization_coverage.py

# Test input validation
python test_validation.py

# Test with MCP Inspector
npx @modelcontextprotocol/inspector python sap_datasphere_mcp_server.py

Test Results

• ✅ 42/42 tools registered - All tools properly defined
• ✅ 42/42 tools authorized - Authorization permissions configured
• ✅ 41/42 tools working - 98% success rate
• ✅ 0 code bugs - All implementation issues fixed

---

📁 Project Structure

sap-datasphere-mcp/
├── 📁 auth/                            # Authentication & Security
│   ├── oauth_handler.py                # OAuth 2.0 token management
│   ├── datasphere_auth_connector.py    # Authenticated API connector
│   ├── authorization.py                # Permission-based authorization
│   ├── consent_manager.py              # User consent tracking
│   ├── input_validator.py              # Input validation framework
│   ├── sql_sanitizer.py                # SQL injection prevention
│   └── data_filter.py                  # PII and credential redaction
├── 📁 config/                          # Configuration management
│   └── settings.py                     # Environment-based settings
├── 📁 docs/                            # Documentation
│   ├── OAUTH_SETUP.md                  # OAuth setup guide
│   ├── TROUBLESHOOTING_CLAUDE_DESKTOP.md
│   └── OAUTH_IMPLEMENTATION_STATUS.md
├── 📄 sap_datasphere_mcp_server.py     # Main MCP server (42 tools)
├── 📄 cache_manager.py                 # Intelligent caching
├── 📄 telemetry.py                     # Monitoring and metrics
├── 📄 mock_data_provider.py            # Mock data for testing
├── 📄 .env.example                     # Configuration template
├── 📄 requirements.txt                 # Python dependencies
├── 📄 README.md                        # This file
└── 📄 ULTIMATE_TEST_RESULTS.md         # Comprehensive test results

---

🙏 Acknowledgments

This MCP server was built with significant contributions from:

Amazon Kiro

Provided comprehensive specifications, architectural steering, and development guidance that shaped the MCP server's design and implementation.

Claude Code

AI-powered development assistant that contributed to:

Phase 1: Security & Authentication

• OAuth 2.0 implementation with automatic token refresh
• Permission-based authorization (READ, WRITE, ADMIN, SENSITIVE)
• User consent flows for high-risk operations
• Input validation and SQL sanitization
• Sensitive data filtering and PII redaction

Phase 2: UX & AI Interaction

• Enhanced tool descriptions with examples
• Intelligent error messages with recovery suggestions
• Parameter validation with clear format requirements

Phase 3: Performance & Monitoring

• Intelligent caching with category-based TTL
• Comprehensive telemetry and metrics
• Performance optimization (up to 95% faster for cached queries)

Phase 4: Repository & Analytics

• Repository object discovery tools
• Analytical model access and OData query support
• Metadata extraction and schema discovery

Mock Data Remediation Journey:

• Phase 1: Database User Management (5/5 tools) - SAP CLI integration ✅
• Phase 2: API Syntax Fixes (4/4 tools) - OData filter workarounds ✅
• Phase 3: HTML Response Fixes (2/2 tools) - Graceful degradation ✅
• Phase 4: Search Workarounds (2/2 tools) - Client-side search ✅
• Achievement: From 42.9% → 80% real data integration! 🎯

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📞 Support

• 📚 Documentation: See /docs folder for detailed guides
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 SAP Datasphere: Official Documentation
• 🤖 MCP Protocol: Model Context Protocol

---

🎯 Roadmap

Completed ✅

• OAuth 2.0 authentication with automatic token refresh
• 35 MCP tools implementation
• 🎯 TARGET ACHIEVED: 80% real data integration (28/35 tools)
• Authorization and consent management
• Input validation and SQL sanitization
• Intelligent caching and telemetry
• Phase 1: Database User Management (5/5 tools) - SAP CLI integration
• Phase 2: API Syntax Fixes (4/4 tools) - OData filter workarounds
• Phase 3: HTML Response Fixes (2/2 tools) - Graceful degradation
• Phase 4: Search Workarounds (2/2 tools) - Client-side search
• Comprehensive testing with real SAP Datasphere tenant
• 36+ real assets discovered (HR, Finance, Sales, Time dimensions)
• 100% Foundation, Catalog, Search, Metadata & User Management Tools

Future Enhancements 🔮

• Analytical tools real data integration (requires tenant configuration)
• Enhanced query execution capabilities
• Additional permission scopes for restricted endpoints
• Vector database integration for semantic search
• Real-time event streaming
• Advanced schema visualization
• Multi-tenant support
• Machine learning integration

---