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