IBM watsonx.ai Granite — Claude Code MCP server: what it does
Brings IBM Granite models from your own watsonx.ai project into the agent: chat, generation, embeddings, token counting and time-series forecasting.
claude mcp add --env WATSONX_API_KEY=<WATSONX_API_KEY> --env WATSONX_PROJECT_ID=<WATSONX_PROJECT_ID> --env WATSONX_SPACE_ID=<WATSONX_SPACE_ID> --env WATSONX_URL=<WATSONX_URL> --env WATSONX_MODEL_ID=<WATSONX_MODEL_ID> --transport stdio ibm-watsonx-mcp -- npx -y @three-ws/ibm-watsonx-mcpWhat IBM watsonx.ai Granite does
The server talks to the watsonx.ai REST API directly using your IBM Cloud credentials. It trades WATSONX_API_KEY for a short-lived IAM bearer token, keeps that token in memory and refreshes it shortly before expiry. Nothing sits in between.
Six tools come with it: watsonx_chat, watsonx_generate, watsonx_embed, watsonx_tokenize, watsonx_forecast and watsonx_list_models. Each one only runs inference and leaves your account untouched; annotations like readOnlyHint and idempotentHint tell the client so.
You need Node.js 20 or newer, an IBM Cloud account with watsonx.ai enabled, an API key and a project id. This is a community project with no ties to IBM. Pass the key and project id as environment variables — the server won't start without them.
What it helps with
- send a prompt to Granite from inside the agent
- embed a batch of strings in one call
- count tokens before spending them
- forecast a time series without training a model
- see which foundation models your region offers
Example prompts for the agent
- Ask
watsonx_chatto explain MCP in one sentence - Run
watsonx_embedon the strings “lakehouse” and “data warehouse” - List embedding models only via
watsonx_list_models
How to install IBM watsonx.ai Granite
Platform CLI
claude mcp add --env WATSONX_API_KEY=<WATSONX_API_KEY> --env WATSONX_PROJECT_ID=<WATSONX_PROJECT_ID> --env WATSONX_SPACE_ID=<WATSONX_SPACE_ID> --env WATSONX_URL=<WATSONX_URL> --env WATSONX_MODEL_ID=<WATSONX_MODEL_ID> --transport stdio ibm-watsonx-mcp -- npx -y @three-ws/ibm-watsonx-mcpReplace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
codex mcp add ibm-watsonx-mcp --env WATSONX_API_KEY=<WATSONX_API_KEY> --env WATSONX_PROJECT_ID=<WATSONX_PROJECT_ID> --env WATSONX_SPACE_ID=<WATSONX_SPACE_ID> --env WATSONX_URL=<WATSONX_URL> --env WATSONX_MODEL_ID=<WATSONX_MODEL_ID> -- npx -y @three-ws/ibm-watsonx-mcpReplace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"ibm-watsonx-mcp": {
"command": "npx",
"args": [
"-y",
"@three-ws/ibm-watsonx-mcp"
],
"env": {
"WATSONX_API_KEY": "<WATSONX_API_KEY>",
"WATSONX_PROJECT_ID": "<WATSONX_PROJECT_ID>",
"WATSONX_SPACE_ID": "<WATSONX_SPACE_ID>",
"WATSONX_URL": "<WATSONX_URL>",
"WATSONX_MODEL_ID": "<WATSONX_MODEL_ID>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"ibm-watsonx-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@three-ws/ibm-watsonx-mcp"
],
"env": {
"WATSONX_API_KEY": "<WATSONX_API_KEY>",
"WATSONX_PROJECT_ID": "<WATSONX_PROJECT_ID>",
"WATSONX_SPACE_ID": "<WATSONX_SPACE_ID>",
"WATSONX_URL": "<WATSONX_URL>",
"WATSONX_MODEL_ID": "<WATSONX_MODEL_ID>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
gemini mcp add -e WATSONX_API_KEY=<WATSONX_API_KEY> -e WATSONX_PROJECT_ID=<WATSONX_PROJECT_ID> -e WATSONX_SPACE_ID=<WATSONX_SPACE_ID> -e WATSONX_URL=<WATSONX_URL> -e WATSONX_MODEL_ID=<WATSONX_MODEL_ID> ibm-watsonx-mcp npx -y @three-ws/ibm-watsonx-mcpReplace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about IBM watsonx.ai Granite
How to install IBM watsonx.ai Granite in Claude Code?
One command: claude mcp add ibm-watsonx -e WATSONX_API_KEY=<WATSONX_API_KEY> -- npx -y @three-ws/ibm-watsonx-mcp. Replace the key with your own.
What does IBM watsonx.ai Granite do?
It exposes the models in your watsonx.ai project to the agent: chat, text generation, embeddings, tokenization, forecasting and model listing.
What is required to run it?
Node.js 20 or newer, an IBM Cloud account with watsonx.ai, an IBM Cloud API key and your project id. The last two go into WATSONX_API_KEY and WATSONX_PROJECT_ID.
