Ibm Watsonxdata MCP Server

IBM watsonx.data MCP服务器

概述

IBM Watson data MCP服务器使AI助手能够使用自然语言与IBM Watson data Lakehouse无缝交互。它为全面的湖屋运营提供了6类专业工具：

• 平台管理：实例状态和配置
• 发动机操作：管理和监控Presto和Spark引擎
• 目录管理：浏览模式、表和元数据；修改表结构
• 查询执行：使用查询计划分析运行SELECT、INSERT、UPDATE查询
• Spark应用程序：提交、监视和管理Spark作业
• 数据摄取：将数据从对象存储加载到lakehouse表中

目前，它支持本地子进程的stdio传输和可流式传输的HTTP。有关运输方案的全面详细信息，包括实施指南和安全最佳实践，请参阅 MCP运输规范.

注： IBM watsonx.data还提供了一个无需安装的托管远程MCP服务器。有关使用远程服务器的详细信息，请参阅 远程查询文档.

支持的功能

核心能力

• 多种工具 分为6个功能类别（参见 TOOLS.md)
• 平台工具：实例详细信息和状态
• 引擎工具：Presto和Spark引擎的生命周期管理
• 目录工具：架构和表发现、元数据操作、DDL操作
• 查询工具：使用查询计划分析执行SELECT、INSERT、UPDATE
• Spark应用工具：提交和管理Spark应用程序
• 摄入工具：从对象存储加载数据（CSV、Parquet、JSON）

安全和身份验证

• 带有自动令牌刷新的IBM Cloud IAM身份验证
• 具有适当访问控制的读写操作

运输与集成

• 当前：stdio传输，可流式传输HTTP
• 与Claude Desktop、IBM Bob和其他启用MCP的AI助手兼容

架构概述

flowchart LR
    User --> Assistant[AI Assistant]
    Assistant -->|stdio/JSON-RPC| Server[watsonx.data MCP Server]
    Server -->|IAM Auth + API Calls| WX[watsonx.data Service]
    WX --> Engines[Presto & Spark Engines]
    Engines --> Lakehouse[Lakehouse Storage]

    style Server fill:#f3e5f5,stroke:#4a148c
    style WX fill:#e0f2f1,stroke:#00695c
    style Engines fill:#fff3e0,stroke:#ef6c00

查询执行流程

sequenceDiagram
    participant A as AI Assistant
    participant S as MCP Server
    participant I as IBM Cloud IAM
    participant W as watsonx.data API
    participant E as Presto/Spark Engines

    A->>S: Natural-language request (MCP)
    S->>I: Request IAM token
    I-->>S: IAM access token
    S->>W: API request (catalog, SQL, schema...)
    W->>E: Query execution / metadata ops
    E-->>W: Results
    W-->>S: Response
    S-->>A: Structured MCP result

入门指南

1.先决条件

安装前，请确保：

• Python 3.11或更高版本 (下载)
• uv包管理器 (安装)
• IBM云帐户 (创建账户)
• watsonx.data实例 (配置实例)以及(设置)
• IBM云API密钥 (创建API密钥)
• 收集实例详细信息：

- 基本URL：从您的watsonx.data实例获取： - 选项1：访问实例时从浏览器的地址栏复制主机名，然后追加 /lakehouse/api - 选项2：导航到实例详细信息→ 数据访问服务（DAS）端点 - 示例格式： https://us-south.lakehouse.cloud.ibm.com/lakehouse/api - 实例CRN （例如。， crn:v1:bluemix:public:lakehouse:us-south:a/...) - IAM API密钥 可以访问watsonx.data实例、目录和引擎

2.安装

选项1：使用pip/pipx

pipx install ibm-watsonxdata-mcp-server

如果未安装pipx，您可以使用pip安装MCP服务器：

pip install --user ibm-watsonxdata-mcp-server

选项2：开发设置

# Clone repository
git clone https://github.com/IBM/ibm-watsonxdata-mcp-server.git
cd ibm-watsonxdata-mcp-server

# Install dependencies
uv sync

# Copy example configuration
cp examples/.env.example .env

# Edit with your credentials
export WATSONX_DATA_BASE_URL=https://us-south.lakehouse.cloud.ibm.com/lakehouse/api
export WATSONX_DATA_API_KEY=your_ibm_cloud_api_key_here
export WATSONX_DATA_INSTANCE_ID=crn:v1:bluemix:public:lakehouse:us-south:a/...

# Verify installation
uv run ibm-watsonxdata-mcp-server --transport stdio

3.配置您的AI助手

与Claude Desktop集成

查找您的Claude Desktop配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

将此添加到 claude_desktop_config.json:

选项1：使用pip/pipx安装

首先，找到已安装命令的完整路径：

# macOS/Linux
which ibm-watsonxdata-mcp-server

# Windows (PowerShell)
where.exe ibm-watsonxdata-mcp-server

常见安装路径：

• 带pipx或pip的macOS/Linux用户: ~/.local/bin/ibm-watsonxdata-mcp-server
• 带pipx的窗户: %USERPROFILE%\.local\bin\ibm-watsonxdata-mcp-server.exe
• 全系统安装: /usr/local/bin/ibm-watsonxdata-mcp-server

然后在配置中使用完整路径：

{
  "mcpServers": {
    "IBM watsonx.data MCP Server": {
      "command": "/path/from/which/command/ibm-watsonxdata-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "WATSONX_DATA_BASE_URL": "https://us-south.lakehouse.cloud.ibm.com/lakehouse/api",
        "WATSONX_DATA_API_KEY": "your_api_key_here",
        "WATSONX_DATA_INSTANCE_ID": "crn:v1:bluemix:public:lakehouse:us-south:a/..."
      }
    }
  }
}

选项2：使用开发安装

{
  "mcpServers": {
    "IBM watsonx.data MCP Server": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-watsonx-data",
        "run",
        "ibm-watsonxdata-mcp-server"
      ],
      "env": {
        "WATSONX_DATA_BASE_URL": "https://us-south.lakehouse.cloud.ibm.com/lakehouse/api",
        "WATSONX_DATA_API_KEY": "your_api_key_here",
        "WATSONX_DATA_INSTANCE_ID": "crn:v1:bluemix:public:lakehouse:us-south:a/..."
      }
    }
  }
}

与IBM Bob集成

查找您的mcp_settings.json配置文件： ~/Library/Application Support/IBM Bob/User/globalStorage/ibm.bob-code/settings/mcp_settings.json

不同的版本将有不同的路径。确切的路径将在中找到 Views and More Actions... -> MCP Servers -> Edit MCP

选项1：使用pip/pipx安装

首先，找到完整路径：

which ibm-watsonxdata-mcp-server

然后在配置中使用该路径：

{
  "mcpServers": {
    "IBM watsonx.data MCP Server": {
      "command": "/path/from/which/command/ibm-watsonxdata-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "WATSONX_DATA_BASE_URL": "https://us-south.lakehouse.cloud.ibm.com/lakehouse/api",
        "WATSONX_DATA_API_KEY": "your_api_key_here",
        "WATSONX_DATA_INSTANCE_ID": "crn:v1:bluemix:public:lakehouse:us-south:a/..."
      }
    }
  }
}

选项2：使用开发安装

{
  "mcpServers": {
    "IBM watsonx.data MCP Server": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-watsonx-data",
        "run",
        "ibm-watsonxdata-mcp-server"
      ],
      "env": {
        "WATSONX_DATA_BASE_URL": "https://us-south.lakehouse.cloud.ibm.com/lakehouse/api",
        "WATSONX_DATA_API_KEY": "your_api_key_here",
        "WATSONX_DATA_INSTANCE_ID": "crn:v1:bluemix:public:lakehouse:us-south:a/..."
      }
    }
  }
}

使用流式HTTP传输运行

对于远程访问或基于HTTP的集成：

uv run python -m lakehouse_mcp --transport streamable-http --host 0.0.0.0 --port 9000

可用工具

快速参考

看 TOOLS.md 了解当前支持的工具和高级使用模式。

示例用法

一旦配置了Claude Desktop，您就可以使用自然语言与您的watsonx.data实例进行交互：

1.检查实例状态

你问：

What watsonx.data instance am I connected to?

克劳德回应道：

You're connected to watsonx.data instance:
- Instance ID: crn:v1:bluemix:public:lakehouse:us-south:a/abc123...
- Region: us-south
- Version: 2.0.0
- Status: active
- Serverless Spark: enabled
- Presto: enabled

2.发现可用数据

你问：

What schemas are available in tpch catalog?

克劳德回应道：

Available Schemas:
- `tiny` - TPC-H benchmark data (smallest scale)
- `sf1` through `sf100000` - Various scale factors (1, 10, 100, 300, 1000, 3000, 10000, 30000, 100000)
- `information_schema` - System schema

**Tables in the "tiny" schema:**
1. customer
2. lineitem
3. nation
4. orders
5. part
6. partsupp
7. region
8. supplier

These are the standard TPC-H benchmark tables. Would you like me to:
- Describe the schema of one of these tables?
- Run a sample query on one of the tables?
- Explore tables from a different scale factor (sf1, sf100, etc.)?

3.探索表结构

你问：

Show me the schema for the customer table in tiny schema

克劳德回应道：

Here's the schema for the **customer** table in the **tpch.tiny** schema:

Columns (8 total):

1. `c_custkey` - bigint (nullable)
2. `c_name` - varchar(25) (nullable)
3. `c_address` - varchar(40) (nullable)
4. `c_nationkey` - bigint (nullable)
5. `c_phone` - varchar(15) (nullable)
6. `c_acctbal` - double (nullable)
7. `c_mktsegment` - varchar(10) (nullable)
8. `c_comment` - varchar(117) (nullable)

Table Properties:
- Type: TABLE
- Primary Keys: None
- Partitions: None

This is a standard TPC-H customer table with customer ID, name, address, nation reference, phone, account balance, market segment, and comments. All columns are nullable.

Would you like me to run a query on this table or explore other tables?

4.查询数据

你问：

Show me the top 10 customers by account balance

克劳德执行：

SELECT c_custkey, c_name, c_address, c_phone, c_acctbal, c_mktsegment FROM customer ORDER BY c_acctbal DESC LIMIT 10

并以格式化的表格形式显示结果 以下是按账户余额排名前10位的客户：

查询在42.7秒内执行，返回10行。客户#0000000213的账户余额最高，为9987.71美元。

5.多步分析

你问：

I need to analyze customer data. What's available and what does it look like?

克劳德：

1. 让我检查一下你的watsonx.data实例中有什么
2. 我将浏览tpch目录
3. 这是客户表模式
4. 运行查询以获取客户数据
5. 根据客户表中的列运行更多查询
6. 查看相关表格
7. 呈现摘要

看 TOOLS.md 查看完整的工具列表、更多使用模式和高级示例。

发展

设置开发环境

1. 克隆仓库

   git clone https://github.com/your-org/mcp-watsonx-data.git
   cd mcp-watsonx-data

1. 安装依赖项（包括开发依赖项）

   uv sync --extra dev

1. 设置环境变量

   cp examples/.env.example .env
   # Edit .env with your credentials
   export WATSONX_DATA_BASE_URL=https://us-south.lakehouse.cloud.ibm.com/lakehouse/api
   export WATSONX_DATA_API_KEY=your_ibm_cloud_api_key_here
   export WATSONX_DATA_INSTANCE_ID=crn:v1:bluemix:public:lakehouse:us-south:a/...

运行测试

运行覆盖范围完整的测试套件：

uv run pytest

运行具有详细输出的测试：

uv run pytest -v

运行特定测试文件：

uv run pytest tests/test_client.py

使用覆盖率报告运行测试：

uv run pytest --cov=lakehouse_mcp --cov-report=html

查看覆盖率报告：

open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux
start htmlcov/index.html  # Windows

代码质量

运行linting和格式化：

uv run ruff check .
uv run ruff format .

运行类型检查：

uv run mypy src/

运行预提交钩子：

uv run pre-commit run --all-files

故障排除

看 故障排除.md 用于常见问题、诊断和解决方案。

实用链接

• IBM Watson数据文档: https://cloud.ibm.com/docs/watsonxdata?topic=watsonxdata-开始
• IBM云API密钥: https://cloud.ibm.com/iam/apikeys
• MCP规范: https://modelcontextprotocol.io/