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

License

MIT License. See LICENSE for details.

Acknowledgments

• Model Context Protocol
• Keycloak
• Teradata
• FastMCP