SAP HANA MCP Server

Model Context Protocol (MCP) server for seamless SAP HANA database integration with AI agents and development tools.

📋 Table of Contents

• Overview
• Key Features
• Architecture
• Prerequisites
• Quick Setup
• Configuration
• Usage
• API Reference
• Development
• Troubleshooting
• Contributing
• License

🎯 Overview

The SAP HANA MCP Server provides a robust, production-ready bridge between AI applications and SAP HANA databases through the Model Context Protocol (MCP). Designed for enterprise environments, it offers comprehensive database management capabilities with secure, scalable architecture.

Supported Platforms

• AI Agents: Custom AI Applications, Claude Desktop, VSCode Extensions
• Databases: SAP HANA (All versions)
• Operating Systems: macOS, Linux, Windows
• Node.js: 18.x and above

✨ Key Features

🔐 Enterprise Security

• Secure Credential Management: Environment-based configuration
• SSL/TLS Support: Full encryption for database communications
• Certificate Validation: Configurable certificate verification

🗄️ Database Operations

• Schema Exploration: Complete database schema discovery and navigation
• Query Execution: Advanced SQL query execution with parameterized support
• Administrative Tools: System monitoring, user management, and performance insights
• Data Management: Sample data retrieval, row counting, and metadata analysis

🏗️ Architecture Excellence

• Modular Design: Clean separation of concerns with maintainable codebase
• Scalable Architecture: Easy extension and customization for enterprise needs
• Comprehensive Logging: Structured logging with configurable levels
• Error Handling: Robust error management with detailed diagnostics

🔧 Developer Experience

• MCP Protocol Compliance: Full Model Context Protocol 2.0 implementation
• Tool Discovery: Automatic tool registration and discovery
• JSON-RPC 2.0: Standardized communication protocol
• Testing Framework: Comprehensive testing suite with multiple validation methods

🏗️ Architecture

System Architecture

Component Architecture

hana-mcp-server/
├── 📁 src/
│   ├── 🏗️ server/           # MCP Protocol & Server Management
│   │   ├── index.js         # Main server entry point
│   │   ├── mcp-handler.js   # JSON-RPC 2.0 implementation
│   │   └── lifecycle-manager.js # Server lifecycle management
│   ├── 🛠️ tools/            # Tool Implementations
│   │   ├── index.js         # Tool registry & discovery
│   │   ├── config-tools.js  # Configuration management
│   │   ├── schema-tools.js  # Schema exploration
│   │   ├── table-tools.js   # Table operations
│   │   ├── index-tools.js   # Index management
│   │   └── query-tools.js   # Query execution
│   ├── 🗄️ database/         # Database Layer
│   │   ├── hana-client.js   # HANA client wrapper
│   │   ├── connection-manager.js # Connection management
│   │   └── query-executor.js # Query execution utilities
│   ├── 🔧 utils/            # Shared Utilities
│   │   ├── logger.js        # Structured logging
│   │   ├── config.js        # Configuration management
│   │   ├── validators.js    # Input validation
│   │   └── formatters.js    # Response formatting
│   └── 📋 constants/        # Constants & Definitions
│       ├── mcp-constants.js # MCP protocol constants
│       └── tool-definitions.js # Tool schemas
├── 🧪 tests/                # Testing Framework
├── 📚 docs/                 # Documentation
├── 📦 package.json          # Dependencies & Scripts
└── 🚀 hana-mcp-server.js    # Main entry point

📋 Prerequisites

System Requirements

• Node.js: Version 18.x or higher
• Memory: Minimum 512MB RAM (2GB recommended)
• Storage: 100MB available disk space
• Network: Access to SAP HANA database

Database Requirements

• SAP HANA: Version 2.0 or higher
• User Permissions: SELECT, DESCRIBE, and administrative privileges
• Network Access: TCP/IP connectivity to HANA instance

Development Tools

• Claude Desktop: For AI agent integration
• VSCode: For development and testing (optional)
• Git: For version control

🚀 Quick Setup

Step 1: Install the Package

npm install -g hana-mcp-server

Step 2: Configure Claude Desktop

Update your Claude Desktop configuration file:

macOS: ~/.config/claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json
Windows: %APPDATA%\claude\claude_desktop_config.json

{
  "mcpServers": {
    "HANA Database": {
      "command": "hana-mcp-server",
      "env": {
        "HANA_HOST": "your-hana-host.com",
        "HANA_PORT": "443",
        "HANA_USER": "your-username",
        "HANA_PASSWORD": "your-password",
        "HANA_SCHEMA": "your-schema",
        "HANA_SSL": "true",
        "HANA_ENCRYPT": "true",
        "HANA_VALIDATE_CERT": "true",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop to load the new configuration.

Step 4: Test Connection

Ask Claude: "Test the HANA database connection" or "Show me the available schemas"

That's it! 🎉 Your HANA MCP Server is now ready to use.

⚙️ Configuration

Environment Variables

Default Schema Behavior

The server intelligently handles schema selection:

🚀 Usage

Claude Desktop Integration

Once configured, you can interact with your HANA database using natural language:

• "Show me all schemas in the database"
• "List tables in the SYSTEM schema"
• "Describe the structure of table CUSTOMERS"
• "Execute this query: SELECT * FROM SYSTEM.TABLES LIMIT 10"
• "Get sample data from table ORDERS"

Command Line Usage

You can also run the server directly:

# Start with environment variables
HANA_HOST="your-host" HANA_USER="your-user" HANA_PASSWORD="your-pass" hana-mcp-server

# Or set environment variables first
export HANA_HOST="your-host"
export HANA_USER="your-user"
export HANA_PASSWORD="your-pass"
hana-mcp-server

📚 API Reference

Configuration Tools

Schema Exploration Tools

Query Execution Tools

Administrative Tools

Tool Response Format

All tools return standardized JSON responses:

{
  "content": [
    {
      "type": "text",
      "text": "Tool execution result"
    }
  ],
  "isError": false,
  "error": null
}

🔧 Development

Development Setup

# Clone repository
git clone https://github.com/hatrigt/hana-mcp-server.git
cd hana-mcp-server

# Install dependencies
npm install

# Start development server with auto-reload
npm run dev

Adding New Tools

1. Create Tool Implementation

// src/tools/my-tools.js
const { logger } = require('../utils/logger');
const Formatters = require('../utils/formatters');

class MyTools {
  static async myNewTool(args) {
    logger.tool('my_new_tool', args);
    
    try {
      // Tool implementation
      const result = await this.performOperation(args);
      
      return Formatters.createResponse(result);
    } catch (error) {
      logger.error('Tool execution failed', error);
      return Formatters.createErrorResponse(error.message);
    }
  }
  
  static async performOperation(args) {
    // Tool logic implementation
    return "Operation completed successfully";
  }
}

module.exports = MyTools;

2. Register Tool

// src/tools/index.js
const MyTools = require('./my-tools');

const TOOL_IMPLEMENTATIONS = {
  // ... existing tools
  my_new_tool: MyTools.myNewTool
};

3. Define Tool Schema

// src/constants/tool-definitions.js
{
  name: "my_new_tool",
  description: "Performs a specific operation with detailed description",
  inputSchema: {
    type: "object",
    properties: {
      parameter1: {
        type: "string",
        description: "Description of parameter1"
      },
      parameter2: {
        type: "number",
        description: "Description of parameter2"
      }
    },
    required: ["parameter1"]
  }
}

Development Scripts

{
  "scripts": {
    "start": "node hana-mcp-server.js",
    "dev": "nodemon hana-mcp-server.js",
    "test": "node tests/automated/test-mcp-inspector.js"
  }
}

🐛 Troubleshooting

Common Issues & Solutions

Connection Issues

MCP Protocol Issues

Debugging

Enable Debug Logging

# Set debug logging
export LOG_LEVEL="debug"
export ENABLE_FILE_LOGGING="true"
export ENABLE_CONSOLE_LOGGING="true"

# Monitor logs
tail -f hana-mcp-server.log

Manual Server Testing

# Test with minimal configuration
HANA_HOST="test" HANA_USER="test" HANA_PASSWORD="test" hana-mcp-server

# Test specific functionality
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"hana_test_connection","arguments":{}}}' | hana-mcp-server

Error Codes

The server uses standard JSON-RPC 2.0 error codes:

🤝 Contributing

We welcome contributions from the community! Please follow these guidelines:

Contribution Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following coding standards
4. Add tests for new functionality
5. Update documentation as needed
6. Test thoroughly using MCP Inspector
7. Submit a pull request with detailed description

Development Guidelines

• Code Style: Follow existing code patterns
• Testing: Test new features with MCP Inspector
• Documentation: Update README and inline documentation
• Security: Follow security best practices for database operations
• Performance: Consider performance implications of changes

Pull Request Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement

## Testing
- [ ] MCP Inspector tests pass
- [ ] Manual testing completed
- [ ] No breaking changes

## Checklist
- [ ] Code follows existing patterns
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes

📄 License

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

License Summary

• Commercial Use: ✅ Allowed
• Modification: ✅ Allowed
• Distribution: ✅ Allowed
• Private Use: ✅ Allowed
• Liability: ❌ No liability
• Warranty: ❌ No warranty

🙏 Acknowledgments

• SAP for HANA database technology and support
• Anthropic for Claude Desktop and MCP specification
• MCP Community for protocol development and standards
• Open Source Contributors for valuable feedback and contributions