mcp-天睿数据

Name: mcp-天睿数据
Author: arturborycki

作者：arturborycki6 星标更新：2025-11-07

安装使用来源：spider==github.com

项目介绍

Teradata MCP 服务器与 OAuth 2.1 身份验证

概述

这是一个通过 Teradata 提供安全数据库交互和商业智能能力的模型上下文协议（MCP）服务器实现。该服务器支持运行 SQL 查询、分析业务数据以及具有企业级 OAuth 2.1 身份验证的工作负载管理。

🔐 安全特性

与 Keycloak 集成的 OAuth 2.1 身份验证
使用 JWKS 端点进行 JWT 令牌验证
基于范围的授权，用于细粒度访问控制
符合 RFC 9728 的受保护资源元数据
不透明令牌的令牌内省支持
生产就绪的连接弹性及错误处理
自动重试连接以提高可靠性

组件

工具

服务器提供了全面的数据库和工作负载管理工具：

查询工具

query
- 执行 SELECT 查询以从数据库中读取数据
- 所需范围： teradata:query, teradata:read
- 输入：
  - query (字符串)：要执行的 SELECT SQL 查询
- 返回：作为对象数组的查询结果

架构工具

list_db
- 列出 Teradata 系统中的所有数据库
- 所需范围： teradata:read
- 返回：数据库列表
list_tables
- 列出数据库中的对象
- 所需范围： teradata:read
- 输入：
  - db_name (字符串)：数据库名称
- 返回：在提供的或用户默认数据库下的数据库对象列表
show_tables_details
- 显示关于数据库表的详细信息
- 所需范围： teradata:read
- 输入：
- table_name (字符串)：表名
- db_name (字符串)：数据库名称
- 返回：列名和数据类型的数组

分析工具

list_missing_values
- 列出表中缺失值最多的特征
- 所需范围： teradata:read
list_negative_values
- 列出表中有多少特征具有负值
- 所需范围： teradata:read
list_distinct_values
- 列出表中某一列有多少不同的类别
- 所需范围： teradata:read
standard_deviation
- 表中某一列的平均值和标准差是多少？
- 所需范围： teradata:read

🚀 快速开始

1. 基本设置（无身份验证）

# 克隆仓库
git clone https://github.com/arturborycki/mcp-teradata.git
cd mcp-teradata

# 安装依赖
uv install

# 使用数据库连接运行
uv run teradata-mcp "teradatasql://user:password@host/database"

2. 启用 OAuth 设置

# 复制环境配置
cp .env.example .env

# 编辑 .env 文件以添加您的 OAuth 设置
OAUTH_ENABLED=true
KEYCLOAK_URL=https://your-keycloak.com
KEYCLOAK_REALM=teradata-realm
KEYCLOAK_CLIENT_ID=teradata-mcp
KEYCLOAK_CLIENT_SECRET=your-secret
OAUTH_RESOURCE_SERVER_URL=https://your-mcp-server.com

# 使用 OAuth 运行
uv run teradata-mcp "teradatasql://user:password@host/database"

配置

数据库连接

DATABASE_URI=teradatasql://username:password@hostname/database

连接重试设置

# 数据库连接的最大重试次数（默认：1）
TOOL_RETRY_MAX_ATTEMPTS=1

# 重试之间的延迟时间（秒，默认：1.0）
TOOL_RETRY_DELAY_SECONDS=1.0

OAuth 2.1 设置

# 启用 OAuth 身份验证
OAUTH_ENABLED=true

# Keycloak 配置
KEYCLOAK_URL=https://keycloak.example.com
KEYCLOAK_REALM=teradata-realm
KEYCLOAK_CLIENT_ID=teradata-mcp
KEYCLOAK_CLIENT_SECRET=your-client-secret

# 资源服务器标识
OAUTH_RESOURCE_SERVER_URL=https://your-mcp-server.com

# 可选：所需范围
OAUTH_REQUIRED_SCOPES=teradata:read,teradata:query

# 安全设置
OAUTH_VALIDATE_AUDIENCE=true
OAUTH_VALIDATE_SCOPES=true
OAUTH_REQUIRE_HTTPS=true

支持的 OAuth 范围

teradata:read - 数据库资源的读取权限
teradata:write - 数据库资源的写入权限
teradata:query - 执行 SQL 查询
teradata:admin - 管理权限（TDWM，用户管理）
teradata:schema - 架构管理操作

传输兼容性

OAuth 2.1 身份验证支持所有 MCP 传输方法：

传输方式	OAuth 支持	发现端点	备注
SSE	✅ 完整支持	✅ 可用	OAuth 端点集成到 Starlette 应用
可流式传输 HTTP	✅ 完整支持	✅ 可用	通过 FastMCP FastAPI 集成的 OAuth 端点
Stdio	➖ 不适用	➖ 不适用	无 HTTP 端点，通过环境进行身份验证

可用的发现端点：

/.well-known/oauth-protected-resource - 受保护资源元数据（RFC 9728）
/.well-known/mcp-server-info - MCP 服务器能力和 OAuth 配置
/health - 包含 OAuth 状态的健康检查

传输选择：

# SSE（服务器发送事件）- 推荐用于 Web 应用程序
export MCP_TRANSPORT=sse
export MCP_HOST=0.0.0.0
export MCP_PORT=8000

# 可流式传输 HTTP - 推荐用于 API 集成
export MCP_TRANSPORT=streamable-http
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export MCP_PATH=/mcp/

# Stdio - 用于命令行客户端（Claude Desktop）
export MCP_TRANSPORT=stdio

🐳 Docker 部署

无 OAuth（开发）

docker-compose up -d

启用 OAuth（生产）

# 编辑 docker-compose.oauth.yml 中的环境变量
docker-compose -f docker-compose.oauth.yml up -d

包含 Keycloak（测试）

# 包括 Keycloak 服务器用于测试
docker-compose -f docker-compose.oauth.yml up keycloak mcp-teradata

🔑 Keycloak 设置

自动化设置

使用提供的脚本来自动配置 Keycloak：

# 本地开发
./scripts/setup-keycloak.sh http://localhost:8080 admin admin

# 远程 Keycloak
./scripts/setup-keycloak.sh https://your-keycloak.com admin-user admin-pass

手动设置

请参阅详细的 Keycloak 配置指南：docs/OAUTH.md

🧪 测试 OAuth

测试您的 OAuth 配置：

# 运行 OAuth 测试
./scripts/test-oauth.py

# 使用自定义设置测试
./scripts/test-oauth.py --keycloak-url https://your-keycloak.com --realm your-realm

📋 API 端点

当启用 OAuth 时，服务器会暴露发现端点：

/.well-known/oauth-protected-resource - 受保护资源元数据（RFC 9728）
/.well-known/mcp-server-info - MCP 服务器能力和 OAuth 信息
/health - 包含 OAuth 状态的健康检查

与 Claude Desktop 的使用

基本配置

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

启用 OAuth 的配置

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/MCP/mcp-teradata",
        "run",
        "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://user:passwd@host/database",
        "OAUTH_ENABLED": "true",
        "KEYCLOAK_URL": "https://your-keycloak.com",
        "KEYCLOAK_REALM": "teradata-realm",
        "KEYCLOAK_CLIENT_ID": "teradata-mcp",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "OAUTH_RESOURCE_SERVER_URL": "https://your-server.com"
      }
    }
  }
}

# 将服务器添加到您的 claude_desktop_config.json
{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/MCP/mcp-teradata",
        "run",
        "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradata://user:passwd@host"
      }
    }
  }
}

作为 API 容器的使用

确保编辑 docker-compose.yml 并更新环境变量

docker compose build
docker compose up

🔧 构建

uv build

📚 文档

OAuth 2.1 指南 - 详尽的 OAuth 设置和使用指南
Keycloak 配置 - 自动化的 Keycloak 设置
环境变量 - 配置参考

🔒 安全最佳实践

在生产环境中使用 HTTPS (OAUTH_REQUIRE_HTTPS=true)
使用环境变量或密钥管理来保护客户端密钥
为长时间运行的应用程序实现适当的令牌刷新
分配范围时遵循最小特权原则
定期审核用户权限和访问日志

🐛 故障排除

常见问题

OAuth 身份验证失败：

# 测试 Keycloak 连接
curl https://your-keycloak.com/auth/realms/master/.well-known/openid-configuration

# 检查服务器健康状况
curl https://your-mcp-server.com/health

数据库连接问题：

验证 DATABASE_URI 格式：teradatasql://user:pass@host/database
检查到 Teradata 服务器的网络连接
确保数据库凭据正确
默认情况下，连接问题会自动重试一次

连接重试配置：

设置 TOOL_RETRY_MAX_ATTEMPTS 来控制重试行为（0 = 不重试）
设置 TOOL_RETRY_DELAY_SECONDS 来控制重试之间的延迟
监控日志中的重试尝试消息

权限被拒绝错误：

验证用户是否具有所需的 OAuth 范围
检查 Keycloak 角色分配
查看客户端配置中的范围映射

调试模式

启用调试日志记录：

export LOG_LEVEL=DEBUG
export OAUTH_ENABLED=true
uv run teradata-mcp "teradatasql://user:pass@host/db"

🤝 贡献

欢迎贡献！请：

分叉仓库
创建一个功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m '添加神奇的功能')
推送到分支 (git push origin feature/amazing-feature)
打开一个拉取请求

📄 许可证

此 MCP 服务器根据 MIT 许可证发布。这意味着您可以自由地使用、修改和分发软件，但需遵守 MIT 许可证的条款和条件。更多详情，请参阅项目仓库中的 LICENSE 文件。

🙏 致谢

模型上下文协议规范
Keycloak 用于 OAuth 2.1 实现
Teradata 用于数据库平台
FastMCP 用于 MCP 服务器框架