ibm-watsonxdata

This MCP server exposes tools to interact with IBM watsonx.data lakehouses via natural language prompts and structured tool calls. It supports features such as listing engines, exploring catalogs and metadata, inspecting table schemas, and executing SQL or natural-language queries against lakehouse data. The server operates over the stdio transport, enabling local subprocess usage and JSON-RPC style communication with an AI assistant. After configuring the MCP server, you can use the provided tools (e.g., get_instance_details, list_engines, list_schemas, list_tables, describe_table, execute_select) to perform data operations and obtain structured results suitable for conversational responses.

Prerequisites:

• Python 3.11 or higher
• uv package manager
• IBM Cloud account and watsonx.data instance credentials
• Access to a watsonx.data base URL, API key, and instance CRN

Option 1: Using uv (development-focused) installation

1. Clone the repository and navigate to the project folder
2. Install dependencies and set up the environment
3. Run the MCP server with stdio transport

Example commands:

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

# Install dependencies (via uv)
uv sync

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

# Run the MCP server (stdio transport)
uv run ibm-watsonxdata-mcp-server --transport stdio

Option 2: Using a development installation with uv (alternative workflow)

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

# Install uv and project dependencies
uv sync

# Prepare environment variables
export WATSONX_DATA_BASE_URL=https://us-south.lakehouse.cloud.ibm.com/lakehouse/api
export WATSONX_DATA_API_KEY=your_api_key_here
export WATSONX_DATA_INSTANCE_ID=crn:v1:bluemix:public:lakehouse:us-south:a/...

# Run the MCP server via uv command (reference)
uv run ibm-watsonxdata-mcp-server --transport stdio

Prerequisites recap: ensure Python 3.11+, uv (the package manager), and access credentials for watsonx.data are available before starting the server.

Notes and tips:

• The server uses a read-only, safety-validated mode (SELECTs) by default to protect data.
• Environment variables WATSONX_DATA_BASE_URL, WATSONX_DATA_API_KEY, and WATSONX_DATA_INSTANCE_ID must be supplied to enable API calls to watsonx.data.
• If you switch transports later, follow the MCP Transports Specification for proper setup.
• For local development, you can point uv to the repository path and run the server with the appropriate --directory and run arguments as shown in the development setup.
• When integrating with Claude Desktop or IBM Bob, ensure the MCP server path and environment are accessible by the integration layer and that API keys are kept secure.