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

• 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

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

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

• 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

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

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

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

Add to your claude_desktop_config.json:

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

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

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

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

Discovery endpoints (when OAuth enabled):

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

docker compose up -d

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

uv build

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

MIT License. See LICENSE for details.

• Model Context Protocol
• Keycloak
• Teradata
• FastMCP