Teradata MCP 服务器

一个用于 Teradata 数据库的模型上下文协议 (MCP) 服务器，支持 OAuth 2.1 身份验证、多种身份验证机制 (TD2, LDAP, Kerberos) 以及交互式数据可视化。

功能特性

多种身份验证机制 — TD2 (默认), LDAP, Kerberos, 通过 Teradata LOGMECH 使用 JWT
OAuth 2.1 — 集成 Keycloak，支持 JWT 验证和基于作用域 (scope) 的授权
受保护资源元数据 (符合 RFC 9728 标准)
交互式可视化 — 基于 ECharts 的 MCP 应用，支持 19 种图表类型
连接弹性 — 具备指数退避算法的自动重试机制
非阻塞 I/O — 所有数据库操作均通过 asyncio.to_thread() 运行
工具级 QueryBand — 用于 Teradata 工作负载管理的审计追踪

工具

查询工具

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

模式工具

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

分析工具

list_missing_values — 统计各列的 NULL 值数量
list_negative_values — 统计各列的负值数量
list_distinct_values — 统计各列的不同类别数量
standard_deviation — 计算某列的平均值和标准差

MCP 应用 — 交互式可视化

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 (Simple Bind)	`authcid=user@domain.com`
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 领域名称	—
`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	N/A	N/A	Claude Desktop, CLI 客户端
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。

Teradata MCP Server