# 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