Content
# IBM Cloud MCP Server
A **comprehensive** Model Context Protocol (MCP) server for managing **all** IBM Cloud services. Provides **180+ tools** across 16 service domains, enabling AI assistants to fully manage your IBM Cloud infrastructure.
## ✨ Features
| Domain | Tools | Services |
|:---|:---:|:---|
| **IAM & Identity** | 18 | API keys, users, service IDs, access groups, policies |
| **VPC Infrastructure** | 35 | VPCs, VSIs, subnets, security groups, floating IPs, load balancers, VPN, SSH keys |
| **Kubernetes** | 14 | Clusters, worker pools, add-ons, versions |
| **Cloud Object Storage** | 12 | Buckets, objects, CORS, lifecycle |
| **Code Engine** | 16 | Projects, apps, jobs, builds, secrets |
| **Databases** | 10 | PostgreSQL, Redis, MongoDB, MySQL, backups, scaling |
| **Watson AI** | 8 | watsonx.ai models, text generation, deployments |
| **Networking** | 12 | DNS Services, Transit Gateway, Direct Link |
| **Security** | 12 | Secrets Manager, Key Protect |
| **Resource Management** | 10 | Resource instances, groups, keys |
| **Billing & Usage** | 5 | Account usage, resource costs |
| **Schematics** | 8 | Terraform workspaces, plan, apply |
| **Container Registry** | 6 | Namespaces, images |
| **Cloud Foundry** | 6 | Apps, services, routes |
| **Global Catalog** | 3 | Service search, plans |
| **Observability** | 5 | Logging, monitoring, Activity Tracker |
## 🚀 Quick Start
### Prerequisites
- **Node.js** 18 or higher
- **IBM Cloud API Key** ([Create one here](https://cloud.ibm.com/iam/apikeys))
### Installation
```bash
# Clone and install
git clone <repository-url>
cd IBM_cloud_MCP_SERVER
npm install
npm run build
```
### Configuration
Set your IBM Cloud API key as an environment variable:
```bash
# Required
export IBM_CLOUD_API_KEY="your-api-key"
# Optional (defaults shown)
export IBM_CLOUD_REGION="us-south"
export IBM_CLOUD_ALLOW_WRITE="false"
export IBM_CLOUD_ACCOUNT_ID=""
```
### Usage with Claude Desktop
Add to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"ibm-cloud": {
"command": "node",
"args": ["<path-to>/IBM_cloud_MCP_SERVER/dist/index.js"],
"env": {
"IBM_CLOUD_API_KEY": "your-api-key",
"IBM_CLOUD_REGION": "us-south",
"IBM_CLOUD_ALLOW_WRITE": "true"
}
}
}
}
```
### Usage with Cursor
Add to your Cursor MCP settings (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"ibm-cloud": {
"command": "node",
"args": ["<path-to>/IBM_cloud_MCP_SERVER/dist/index.js"],
"env": {
"IBM_CLOUD_API_KEY": "your-api-key",
"IBM_CLOUD_REGION": "us-south",
"IBM_CLOUD_ALLOW_WRITE": "true"
}
}
}
}
```
## 🐳 Usage with Docker
You can also run the server inside a Docker container. This is useful if you don't want to install Node.js on your host machine.
### Build the Image
```bash
docker build -t ibm-cloud-mcp-server .
```
### Configuration for Claude Desktop
Update your `claude_desktop_config.json` to use Docker:
```json
{
"mcpServers": {
"ibm-cloud": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "IBM_CLOUD_API_KEY",
"-e", "IBM_CLOUD_REGION=us-south",
"-e", "IBM_CLOUD_ALLOW_WRITE=true",
"ibm-cloud-mcp-server"
],
"env": {
"IBM_CLOUD_API_KEY": "your-api-key"
}
}
}
}
```
*Note: The `-i` flag is required for interactive mode (stdio).*
## 🔒 Safety
By default, **write operations are disabled**. The server operates in read-only mode.
To enable write operations (create, update, delete):
```bash
export IBM_CLOUD_ALLOW_WRITE="true"
```
## 🏗️ Architecture
```
src/
├── index.ts # Entry point (stdio transport)
├── server.ts # McpServer setup & tool registration
├── config.ts # Environment config & API endpoints
├── auth/
│ └── iam-auth.ts # IAM token management (auto-refresh)
├── lib/
│ ├── api-client.ts # HTTP client with retry logic
│ ├── errors.ts # Error types & parsing
│ └── utils.ts # Shared utilities
└── tools/
├── iam/ # IAM & Identity
├── vpc/ # VPC Infrastructure
├── kubernetes/ # Kubernetes / OpenShift
├── cos/ # Cloud Object Storage
├── code-engine/ # Code Engine
├── databases/ # Databases (PostgreSQL, Redis, etc.)
├── watson/ # Watson AI / watsonx.ai
├── networking/ # DNS, Transit Gateway, Direct Link
├── security/ # Secrets Manager, Key Protect
├── resource-management/ # Resource instances & groups
├── billing/ # Billing & usage reports
├── schematics/ # Schematics (Terraform)
├── container-registry/ # Container Registry
├── cloud-foundry/ # Cloud Foundry
├── catalog/ # Global Catalog
└── observability/ # Logging, Monitoring, Activity Tracker
```
## 📋 Tool Reference
### IAM & Identity
- `iam_get_token_info` - Get current token/account info
- `iam_list_api_keys` / `iam_get_api_key` / `iam_create_api_key` / `iam_delete_api_key`
- `iam_list_users` / `iam_invite_user` / `iam_remove_user`
- `iam_list_service_ids` / `iam_get_service_id` / `iam_create_service_id` / `iam_delete_service_id`
- `iam_list_access_groups` / `iam_create_access_group` / `iam_delete_access_group` / `iam_add_member_to_group`
- `iam_list_policies` / `iam_create_policy` / `iam_delete_policy`
### VPC Infrastructure
- `vpc_list_vpcs` / `vpc_get_vpc` / `vpc_create_vpc` / `vpc_delete_vpc`
- `vpc_list_subnets` / `vpc_create_subnet` / `vpc_delete_subnet`
- `vpc_list_instances` / `vpc_get_instance` / `vpc_create_instance` / `vpc_delete_instance`
- `vpc_start_instance` / `vpc_stop_instance` / `vpc_reboot_instance`
- `vpc_list_instance_profiles` / `vpc_list_images`
- `vpc_list_volumes` / `vpc_create_volume` / `vpc_delete_volume`
- `vpc_list_security_groups` / `vpc_create_security_group` / `vpc_delete_security_group` / `vpc_add_sg_rule`
- `vpc_list_floating_ips` / `vpc_reserve_floating_ip` / `vpc_release_floating_ip`
- `vpc_list_public_gateways` / `vpc_create_public_gateway`
- `vpc_list_network_acls` / `vpc_create_network_acl`
- `vpc_list_ssh_keys` / `vpc_create_ssh_key` / `vpc_delete_ssh_key`
- `vpc_list_load_balancers` / `vpc_create_load_balancer`
- `vpc_list_vpn_gateways` / `vpc_create_vpn_gateway`
### Kubernetes
- `ks_list_clusters` / `ks_get_cluster` / `ks_create_cluster` / `ks_delete_cluster`
- `ks_list_worker_pools` / `ks_create_worker_pool` / `ks_resize_worker_pool` / `ks_delete_worker_pool`
- `ks_list_workers` / `ks_get_cluster_config` / `ks_get_cluster_versions`
- `ks_list_addons` / `ks_enable_addon` / `ks_disable_addon`
### Cloud Object Storage
- `cos_list_buckets` / `cos_create_bucket` / `cos_delete_bucket` / `cos_get_bucket_config`
- `cos_list_objects` / `cos_get_object` / `cos_put_object` / `cos_delete_object`
- `cos_copy_object` / `cos_get_object_metadata`
- `cos_set_bucket_cors` / `cos_set_bucket_lifecycle`
### Code Engine
- `ce_list_projects` / `ce_get_project` / `ce_create_project` / `ce_delete_project`
- `ce_list_apps` / `ce_create_app` / `ce_update_app` / `ce_delete_app`
- `ce_list_jobs` / `ce_create_job` / `ce_run_job` / `ce_delete_job`
- `ce_list_builds` / `ce_create_build`
- `ce_list_secrets` / `ce_create_secret`
### And 80+ more tools across Databases, Watson AI, Networking, Security, Billing, Schematics, and more...
## 📄 License
MIT
