Teradata MCP Server

Teradata MCP Server

用于 Teradata 数据库的模型上下文协议（MCP）服务，支持 OAuth 2.1 身份验证、多种身份验证机制（TD2、LDAP、Kerberos）和交互式数据可视化。

功能

• 多种身份验证机制 — TD2（默认）、LDAP、Kerberos，以及通过 Teradata LOGMECH 实现的 JWT
• OAuth 2.1，集成 Keycloak、支持 JWT 验证和基于范围的授权
• 受保护资源元数据（符合 RFC 9728）
• 交互式可视化 — 基于 ECharts 的 MCP App，支持 19 种图表类型
• 连接弹性 — 自动重试，并采用指数退避策略
• 非阻塞 I/O — 所有数据库操作均通过 asyncio.to_thread() 执行
• 每个工具的 QueryBand — 用于 Teradata 工作负载管理的审计跟踪

工具

查询工具

• query — 执行 SQL 查询，返回纯表格结果
• visualize_query — 执行 SQL，并通过 MCP App 渲染交互式 ECharts 图表

架构工具

• list_db — 列出所有数据库
• list_tables — 列出数据库中的表／视图
• show_tables_details — 显示表的列名和类型

分析工具

• list_missing_values — 列出包含 NULL 值的列及其数量
• list_negative_values — 列出包含负值的列及其数量
• list_distinct_values — 列出每列中不同类别的数量
• standard_deviation — 计算列的均值和标准差

MCP App — 交互式可视化

visualize_query 工具会在 MCP 客户端中将结果渲染为交互式图表。

类别	图表
柱状图	基础、分组、堆叠、水平、排序、瀑布、圆角、极坐标
折线图	基础、平滑、面积、堆叠面积、阶梯
饼图	饼图、圆环图、玫瑰图／南丁格尔图
散点图	散点图、气泡图
混合图	柱状图 + 折线图

快速开始

安装

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

使用 TD2 运行（标准身份验证）

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

或通过环境变量运行：

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

配置

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

TD2（用户名／密码）

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

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

authcid 的格式取决于 LDAP 目录：

目录	格式
Active Directory（简单绑定）	[email protected]
Active Directory（DIGEST-MD5）	authcid=DOMAIN\username
OpenLDAP / Sun DS	authcid=username

Kerberos 身份验证

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

启用 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"
      }
    }
  }
}

环境变量

数据库连接

变量	描述	默认值
DATABASE_URI	Teradata 连接 URL（teradatasql://user:pass@host/db）	—
DB_LOGMECH	身份验证机制：TD2、LDAP、KRB5、TDNEGO、JWT	TD2
DB_LOGDATA	LDAP／JWT 凭据（例如，authcid=user password=pass）	—
DB_SSL_MODE	TLS 模式：ALLOW、PREFER、REQUIRE、VERIFY-CA、VERIFY-FULL	—
DB_ENCRYPT_DATA	启用传输加密	true

连接弹性

变量	描述	默认值
DB_MAX_RETRIES	最大重连次数	3
DB_INITIAL_BACKOFF	初始退避延迟（秒）	1.0
DB_MAX_BACKOFF	最大退避延迟（秒）	30.0

MCP 传输

变量	描述	默认值
MCP_TRANSPORT	传输方式：stdio、sse、streamable-http	stdio
MCP_HOST	HTTP 传输的绑定地址	localhost
MCP_PORT	HTTP 传输的端口	8000
MCP_PATH	streamable-http 的路径	/mcp/

OAuth 2.1

变量	描述	默认值
OAUTH_ENABLED	启用 OAuth 身份验证	false
KEYCLOAK_URL	Keycloak 服务 URL	—
KEYCLOAK_REALM	Keycloak realm 名称	—
KEYCLOAK_CLIENT_ID	OAuth 客户端 ID	—
KEYCLOAK_CLIENT_SECRET	OAuth 客户端密钥	—
OAUTH_RESOURCE_SERVER_URL	资源服务 URL	—
OAUTH_REQUIRED_SCOPES	必需的作用域（以逗号分隔）	—
OAUTH_VALIDATE_AUDIENCE	验证令牌受众	true
OAUTH_VALIDATE_SCOPES	验证令牌作用域	true
OAUTH_REQUIRE_HTTPS	要求 OAuth URL 使用 HTTPS	true
CORS_ALLOWED_ORIGINS	CORS 允许的来源	*

OAuth 作用域

作用域	描述
teradata:read	数据库资源的读取权限
teradata:write	数据库资源的写入权限
teradata:query	执行 SQL 查询
teradata:admin	管理权限
teradata:schema	模式管理操作

传输兼容性

传输方式	OAuth	发现端点	使用场景
stdio	不适用	不适用	Claude Desktop、命令行客户端
SSE	完整支持	可用	Web 应用
Streamable HTTP	完整支持	可用	API 集成

启用 OAuth 时的发现端点：

• /.well-known/oauth-protected-resource — RFC 9728 元数据
• /.well-known/mcp-server-info — MCP 功能
• /health — 健康检查

Docker 部署

开发

docker compose up -d

使用 OAuth

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

构建

uv build

故障排除

数据库连接问题：

• 验证 DATABASE_URI 格式：teradatasql://user:pass@host/database
• 检查与 Teradata 服务的网络连接
• 对于 LDAP：确保正确设置 DB_LOGMECH=LDAP 和 DB_LOGDATA
• 连接问题会自动重试（可通过 DB_MAX_RETRIES 配置）

LDAP 身份验证失败：

• 验证 Teradata 服务已在 TDGSS 中配置 LDAP
• 检查 authcid 格式是否与目录类型匹配
• 对密码中的特殊字符进行转义（@ → \@，空格 → 使用引号）

权限被拒绝错误：

• 验证用户具有所需的 OAuth 作用域
• 检查 Keycloak 角色分配
• visualize_query 需要 teradata:query 作用域（仅有 teradata:read 不够）

调试日志：

export LOG_LEVEL=DEBUG
uv run teradata-mcp

许可证

MIT 许可证。详情请参阅 LICENSE。

致谢

• Model Context Protocol
• Keycloak
• Teradata
• FastMCP