Securely Query Teradata with OAuth

Teradata MCP Server

A Model Context Protocol (MCP) server for Teradata database with OAuth 2.1 authentication, multiple authentication mechanisms (TD2, LDAP, Kerberos), and interactive data visualization.

Features

• Multiple Auth Mechanisms - TD2 (default), LDAP, Kerberos, JWT via Teradata LOGMECH
• OAuth 2.1 with Keycloak integration, JWT validation, scope-based authorization
• Protected Resource Metadata (RFC 9728 compliant)
• Interactive Visualization - ECharts-based MCP App with 19 chart types
• Connection Resilience - automatic retry with exponential backoff
• Non-blocking I/O - all DB operations run via asyncio.to_thread()
• Per-tool QueryBand - audit trail for Teradata workload management

Tools

Query Tools

• query - Execute SQL queries, return plain tabular results
• visualize_query - Execute SQL and render interactive ECharts charts via MCP App

Schema Tools

• list_db - List all databases
• list_tables - List tables/views in a database
• show_tables_details - Show column names and types for a table

Analysis Tools

• list_missing_values - Columns with NULL value counts
• list_negative_values - Columns with negative value counts
• list_distinct_values - Distinct category counts per column
• standard_deviation - Mean and standard deviation for a column

MCP App - Interactive Visualization

The visualize_query tool renders results as interactive charts in the MCP client.

Quick Start

Installation

git clone https://github.com/arturborycki/mcp-teradata.git
cd mcp-teradata
uv sync

Run with TD2 (Standard Authentication)

uv run teradata-mcp "teradatasql://user:password@host/database"

Or via environment variable:

export DATABASE_URI="teradatasql://user:password@host/database"
uv run teradata-mcp

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

TD2 (Username/Password)

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://user:password@host/database"
      }
    }
  }
}

LDAP Authentication

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://@host/database",
        "DB_LOGMECH": "LDAP",
        "DB_LOGDATA": "authcid=ldap_user password=ldap_password"
      }
    }
  }
}

The authcid format depends on the LDAP directory:

Kerberos Authentication

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://@host/database",
        "DB_LOGMECH": "KRB5"
      }
    }
  }
}

OAuth-Enabled Configuration

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://user:password@host/database",
        "OAUTH_ENABLED": "true",
        "KEYCLOAK_URL": "https://your-keycloak.example.com",
        "KEYCLOAK_REALM": "teradata-realm",
        "KEYCLOAK_CLIENT_ID": "teradata-mcp",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "OAUTH_RESOURCE_SERVER_URL": "https://your-mcp-server.example.com"
      }
    }
  }
}

Environment Variables

Database Connection

Connection Resilience

MCP Transport

OAuth 2.1

OAuth Scopes

Transport Compatibility

Discovery endpoints (when OAuth enabled):

• /.well-known/oauth-protected-resource - RFC 9728 metadata
• /.well-known/mcp-server-info - MCP capabilities
• /health - Health check

Docker Deployment

Development

docker compose up -d

With OAuth

docker compose -f docker-compose.oauth.yml up -d

Build

uv build

Troubleshooting

Database connection issues:

• Verify DATABASE_URI format: teradatasql://user:pass@host/database
• Check network connectivity to Teradata server
• For LDAP: ensure DB_LOGMECH=LDAP and DB_LOGDATA are set correctly
• Connection issues are automatically retried (configurable via DB_MAX_RETRIES)

LDAP authentication fails:

• Verify the Teradata server has LDAP configured in TDGSS
• Check authcid format matches your directory type
• Escape special characters in passwords (@ → \@, spaces → use quotes)

Permission denied errors:

• Verify user has required OAuth scopes
• Check Keycloak role assignments
• visualize_query requires teradata:query scope (not just teradata:read)

Debug logging:

export LOG_LEVEL=DEBUG
uv run teradata-mcp