Teradata MCP Server

Interaja com bancos de dados Teradata para consultas de dados e inteligência de negócios.

Documentação

Servidor MCP Teradata

Um servidor Model Context Protocol (MCP) para banco de dados Teradata com autenticação OAuth 2.1, múltiplos mecanismos de autenticação (TD2, LDAP, Kerberos) e visualização interativa de dados.

Recursos

Múltiplos Mecanismos de Autenticação — TD2 (padrão), LDAP, Kerberos, JWT via Teradata LOGMECH
OAuth 2.1 com integração Keycloak, validação JWT, autorização baseada em escopos
Metadados de Recursos Protegidos (compatível com RFC 9728)
Visualização Interativa — App MCP baseado em ECharts com 19 tipos de gráficos
Resiliência de Conexão — nova tentativa automática com backoff exponencial
I/O Não Bloqueante — todas as operações de banco de dados executadas via asyncio.to_thread()
QueryBand por Ferramenta — trilha de auditoria para gerenciamento de carga de trabalho Teradata

Ferramentas

Ferramentas de Consulta

query — Executa consultas SQL, retorna resultados tabulares simples
visualize_query — Executa SQL e renderiza gráficos ECharts interativos via App MCP

Ferramentas de Esquema

list_db — Lista todos os bancos de dados
list_tables — Lista tabelas/visões em um banco de dados
show_tables_details — Mostra nomes de colunas e tipos de uma tabela

Ferramentas de Análise

list_missing_values — Colunas com contagens de valores NULL
list_negative_values — Colunas com contagens de valores negativos
list_distinct_values — Contagens de categorias distintas por coluna
standard_deviation — Média e desvio padrão para uma coluna

App MCP — Visualização Interativa

A ferramenta visualize_query renderiza resultados como gráficos interativos no cliente MCP.

Categoria	Gráficos
Barra	Básico, Agrupado, Empilhado, Horizontal, Ordenado, Cascata, Arredondado, Polar
Linha	Básico, Suave, Área, Área Empilhada, Degrau
Pizza	Pizza, Rosca, Rosa / Nightingale
Dispersão	Dispersão, Bolha
Misto	Barra + Linha

Início Rápido

Instalação

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

Executar com TD2 (Autenticação Padrão)

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

Ou via variável de ambiente:

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

Configuração

Claude Desktop

Adicione ao seu claude_desktop_config.json:

TD2 (Usuário/Senha)

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

Autenticação LDAP

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

O formato authcid depende do diretório LDAP:

Diretório	Formato
Active Directory (Simple Bind)	`authcid=user@domain.com`
Active Directory (DIGEST-MD5)	`authcid=DOMAIN\username`
OpenLDAP / Sun DS	`authcid=username`

Autenticação Kerberos

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

Configuração Habilitada para OAuth

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

Variáveis de Ambiente

Conexão com Banco de Dados

Variável	Descrição	Padrão
`DATABASE_URI`	URL de conexão Teradata (`teradatasql://user:pass@host/db`)	—
`DB_LOGMECH`	Mecanismo de autenticação: `TD2`, `LDAP`, `KRB5`, `TDNEGO`, `JWT`	`TD2`
`DB_LOGDATA`	Credenciais LDAP/JWT (ex.: `authcid=user password=pass`)	—
`DB_SSL_MODE`	Modo TLS: `ALLOW`, `PREFER`, `REQUIRE`, `VERIFY-CA`, `VERIFY-FULL`	—
`DB_ENCRYPT_DATA`	Habilita criptografia de transporte	`true`

Resiliência de Conexão

Variável	Descrição	Padrão
`DB_MAX_RETRIES`	Máximo de tentativas de reconexão	`3`
`DB_INITIAL_BACKOFF`	Atraso inicial de backoff (segundos)	`1.0`
`DB_MAX_BACKOFF`	Atraso máximo de backoff (segundos)	`30.0`

Transporte MCP

Variável	Descrição	Padrão
`MCP_TRANSPORT`	Transporte: `stdio`, `sse`, `streamable-http`	`stdio`
`MCP_HOST`	Endereço de bind para transportes HTTP	`localhost`
`MCP_PORT`	Porta para transportes HTTP	`8000`
`MCP_PATH`	Caminho para streamable-http	`/mcp/`

OAuth 2.1

Variável	Descrição	Padrão
`OAUTH_ENABLED`	Habilita autenticação OAuth	`false`
`KEYCLOAK_URL`	URL do servidor Keycloak	—
`KEYCLOAK_REALM`	Nome do realm Keycloak	—
`KEYCLOAK_CLIENT_ID`	ID do cliente OAuth	—
`KEYCLOAK_CLIENT_SECRET`	Segredo do cliente OAuth	—
`OAUTH_RESOURCE_SERVER_URL`	URL do servidor de recursos	—
`OAUTH_REQUIRED_SCOPES`	Escopos necessários (separados por vírgula)	—
`OAUTH_VALIDATE_AUDIENCE`	Validar audiência do token	`true`
`OAUTH_VALIDATE_SCOPES`	Validar escopos do token	`true`
`OAUTH_REQUIRE_HTTPS`	Exigir HTTPS para URLs OAuth	`true`
`CORS_ALLOWED_ORIGINS`	Origens permitidas para CORS	`*`

Escopos OAuth

Escopo	Descrição
`teradata:read`	Acesso de leitura aos recursos do banco de dados
`teradata:write`	Acesso de escrita aos recursos do banco de dados
`teradata:query`	Executar consultas SQL
`teradata:admin`	Acesso administrativo
`teradata:schema`	Operações de gerenciamento de esquema

Compatibilidade de Transporte

Transporte	OAuth	Endpoints de Descoberta	Caso de Uso
stdio	N/A	N/A	Claude Desktop, clientes CLI
SSE	Completo	Disponível	Aplicações web
HTTP Streamable	Completo	Disponível	Integrações de API

Endpoints de descoberta (quando OAuth habilitado):

/.well-known/oauth-protected-resource — metadados RFC 9728
/.well-known/mcp-server-info — capacidades MCP
/health — verificação de saúde

Implantação Docker

Desenvolvimento

docker compose up -d

Com OAuth

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

Build

uv build

Solução de Problemas

Problemas de conexão com banco de dados:

Verifique o formato DATABASE_URI: teradatasql://user:pass@host/database
Verifique a conectividade de rede com o servidor Teradata
Para LDAP: garanta que DB_LOGMECH=LDAP e DB_LOGDATA estejam configurados corretamente
Problemas de conexão são automaticamente tentados novamente (configurável via DB_MAX_RETRIES)

Falha na autenticação LDAP:

Verifique se o servidor Teradata tem LDAP configurado no TDGSS
Verifique se o formato authcid corresponde ao tipo do seu diretório
Escape caracteres especiais em senhas (@ → \@, espaços → use aspas)

Erros de permissão negada:

Verifique se o usuário tem os escopos OAuth necessários
Verifique as atribuições de papéis no Keycloak
visualize_query requer escopo teradata:query (não apenas teradata:read)

Registro de depuração:

export LOG_LEVEL=DEBUG
uv run teradata-mcp

Licença

Licença MIT. Consulte LICENSE para detalhes.