Teradata
MCP Server for Teradata database
Installation
npx mcp-teradataAsk AI about Teradata
Powered by Claude Β· Grounded in docs
I know everything about Teradata. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 resultsvisualize_queryβ Execute SQL and render interactive ECharts charts via MCP App
Schema Tools
list_dbβ List all databaseslist_tablesβ List tables/views in a databaseshow_tables_detailsβ Show column names and types for a table
Analysis Tools
list_missing_valuesβ Columns with NULL value countslist_negative_valuesβ Columns with negative value countslist_distinct_valuesβ Distinct category counts per columnstandard_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.
| Category | Charts |
|---|---|
| Bar | Basic, Grouped, Stacked, Horizontal, Sorted, Waterfall, Rounded, Polar |
| Line | Basic, Smooth, Area, Stacked Area, Step |
| Pie | Pie, Doughnut, Rose / Nightingale |
| Scatter | Scatter, Bubble |
| Mixed | Bar + Line |
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:
| Directory | Format |
|---|---|
| Active Directory (Simple Bind) | authcid=user@domain.com |
| Active Directory (DIGEST-MD5) | authcid=DOMAIN\username |
| OpenLDAP / Sun DS | authcid=username |
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
| Variable | Description | Default |
|---|---|---|
DATABASE_URI | Teradata connection URL (teradatasql://user:pass@host/db) | β |
DB_LOGMECH | Authentication mechanism: TD2, LDAP, KRB5, TDNEGO, JWT | TD2 |
DB_LOGDATA | LDAP/JWT credentials (e.g., authcid=user password=pass) | β |
DB_SSL_MODE | TLS mode: ALLOW, PREFER, REQUIRE, VERIFY-CA, VERIFY-FULL | β |
DB_ENCRYPT_DATA | Enable transport encryption | true |
Connection Resilience
| Variable | Description | Default |
|---|---|---|
DB_MAX_RETRIES | Max reconnection attempts | 3 |
DB_INITIAL_BACKOFF | Initial backoff delay (seconds) | 1.0 |
DB_MAX_BACKOFF | Max backoff delay (seconds) | 30.0 |
MCP Transport
| Variable | Description | Default |
|---|---|---|
MCP_TRANSPORT | Transport: stdio, sse, streamable-http | stdio |
MCP_HOST | Bind address for HTTP transports | localhost |
MCP_PORT | Port for HTTP transports | 8000 |
MCP_PATH | Path for streamable-http | /mcp/ |
OAuth 2.1
| Variable | Description | Default |
|---|---|---|
OAUTH_ENABLED | Enable OAuth authentication | false |
KEYCLOAK_URL | Keycloak server URL | β |
KEYCLOAK_REALM | Keycloak realm name | β |
KEYCLOAK_CLIENT_ID | OAuth client ID | β |
KEYCLOAK_CLIENT_SECRET | OAuth client secret | β |
OAUTH_RESOURCE_SERVER_URL | Resource server URL | β |
OAUTH_REQUIRED_SCOPES | Required scopes (comma-separated) | β |
OAUTH_VALIDATE_AUDIENCE | Validate token audience | true |
OAUTH_VALIDATE_SCOPES | Validate token scopes | true |
OAUTH_REQUIRE_HTTPS | Require HTTPS for OAuth URLs | true |
CORS_ALLOWED_ORIGINS | CORS allowed origins | * |
OAuth Scopes
| Scope | Description |
|---|---|
teradata:read | Read access to database resources |
teradata:write | Write access to database resources |
teradata:query | Execute SQL queries |
teradata:admin | Administrative access |
teradata:schema | Schema management operations |
Transport Compatibility
| Transport | OAuth | Discovery Endpoints | Use Case |
|---|---|---|---|
| stdio | N/A | N/A | Claude Desktop, CLI clients |
| SSE | Full | Available | Web applications |
| Streamable HTTP | Full | Available | API integrations |
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_URIformat:teradatasql://user:pass@host/database - Check network connectivity to Teradata server
- For LDAP: ensure
DB_LOGMECH=LDAPandDB_LOGDATAare 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
authcidformat 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_queryrequiresteradata:queryscope (not justteradata:read)
Debug logging:
export LOG_LEVEL=DEBUG
uv run teradata-mcp
License
MIT License. See LICENSE for details.
