code-engine-mcp-server

Code Engine MCP Server

Model Context Protocol (MCP) server for IBM Code Engine and Docker/Podman integration. It enables AI assistants to build, run, push, and deploy containerized workloads with a single MCP server.

📚 Table of Contents

• What You Get
• Quick Start
• Documentation
• Project Structure
• Features
• Configuration
• One-Click Install
• Example Prompts
• Available Tools
• Environment Variables
• Prerequisites
• Development
• Troubleshooting
• Security
• License
• Contributing
• Author
• Support

✨ What You Get

• Container workflow tools for Docker or Podman
• IBM Code Engine project and application management tools
• MCP-ready setup for GitHub Copilot, Cline, and Claude Desktop
• A simple local development and troubleshooting workflow

🚀 Quick Start

# 1) Install dependencies
npm install

# 2) Build the server
npm run build

# 3) Run once to verify
node build/index.js

Then configure your MCP client using one of the examples in the Configuration section below.

📖 Documentation

• Code Engine API Reference
• API Call Scenarios
• Setup Instructions
• Client README
• Cline MCP Config Example
• Code of Conduct
• Contributing Guide
• Maintainers

🗂️ Project Structure

code-engine-mcp-server/
├── api/
│   └── code-engine-openapi.yaml      # OpenAPI reference used for API coverage
├── build/                            # Compiled JavaScript output
├── docs/                             # API references and setup guides
├── internal/                         # Internal release/publishing notes
├── src/                              # Main TypeScript source code
├── CHANGELOG.md                      # Release history
├── CODE_OF_CONDUCT.md                # Community guidelines
├── CONTRIBUTING.md                   # Contribution workflow
├── LICENSE                           # Project license
├── MAINTAINERS.md                    # Maintainer list
├── README.md                         # Project overview and usage
├── mcp.example.json                  # Example MCP client configuration
├── package.json                      # npm package metadata and scripts
├── server.json                       # MCP Registry metadata
└── tsconfig.json                     # TypeScript configuration

🧩 Features

Container Runtime Tools (Docker/Podman)

• ✅ Detect container runtime (Docker/Podman)
• ✅ Build container images
• ✅ Push images to registries
• ✅ List local images
• ✅ Test containers locally
• ✅ Get container logs
• ✅ Stop and remove containers
• ✅ List all containers

IBM Code Engine Tools

• ✅ List Code Engine projects
• ✅ Create applications
• ✅ List applications in a project
• ✅ Get application details

⚙️ Configuration

1) GitHub Copilot (VS Code) - Recommended

Copy mcp.example.json to .vscode/mcp.json in your workspace root:

cp mcp.example.json ../.vscode/mcp.json

Then edit .vscode/mcp.json and replace the placeholder with your IBM Cloud API key:

{
    "servers": {
        "code-engine": {
            "type": "stdio",
            "command": "node",
            "args": [
                "${workspaceFolder}/code-engine-mcp-server/build/index.js"
            ],
            "env": {
                "IBMCLOUD_API_KEY": "your-ibm-cloud-api-key-here"
            }
        }
    }
}

Restart the server: Cmd+Shift+P -> "MCP: Restart Server" -> code-engine.

Security: Add .vscode/mcp.json to your .gitignore to avoid committing your API key.

Get your API key at IBM Cloud IAM → API keys.

2) Cline (VS Code Extension)

• Open VSCode Settings (Cmd/Ctrl + ,)
• Search for "Cline: MCP Settings"
• Click "Edit in settings.json"
• Add the configuration:

{
  "cline.mcpServers": {
    "code-engine": {
      "command": "node",
      "args": ["/absolute/path/to/code-engine-mcp-server/build/index.js"],
      "env": {
        "IBMCLOUD_API_KEY": "your-api-key-here"
      }
    }
  }
}

3) Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "code-engine": {
      "command": "node",
      "args": ["/absolute/path/to/code-engine-mcp-server/build/index.js"],
      "env": {
        "IBMCLOUD_API_KEY": "your-api-key-here"
      }
    }
  }
}

⚡ One-Click Install

Install this MCP server in Cursor with one click:

• Install Code Engine MCP in Cursor

Package and registry links:

• npm package: code-engine-mcp-server
• MCP Registry entry: io.github.markusvankempen/code-engine-mcp-server

💬 Example Prompts

Detect Container Runtime

Ask your assistant:

Can you detect which container runtime I have installed?

Build a Container Image

Ask your assistant:

Build a container image from ./Dockerfile with the name myapp:latest

Test Container Locally

Ask your assistant:

Test the myapp:latest image locally on port 8080

Push to Registry

Ask your assistant:

Push myapp:latest to icr.io/my-namespace/myapp:latest

List Code Engine Projects

Ask your assistant:

List all my Code Engine projects

Complete Workflow

Ask your assistant:

I have a Node.js app in ./my-app with a Dockerfile. Can you:
1. Build it as myapp:v1.0.0
2. Test it locally on port 3000
3. Push it to icr.io/my-namespace/myapp:v1.0.0
4. Deploy it to my Code Engine project "production"
5. Show me the application URL

🛠️ Available Tools

43 tools total: 8 container tools + 35 Code Engine tools.

Container Tools (8)

Tool	Description	Key Parameters
detect_container_runtime	Detect Docker or Podman	—
list_local_images	List local container images	runtime
list_local_containers	List local containers	runtime, all
build_container_image	Build a container image	dockerfile_path, image_name, context_path
push_container_image	Push image to registry	image_name, runtime
test_container_locally	Run container for local testing	image_name, port_mapping, env_vars
get_container_logs	Get logs from a running container	container_id, runtime
stop_local_container	Stop and remove a container	container_id, runtime

Code Engine: Projects (4)

Tool	Description	Key Parameters
ce_list_projects	List all projects in a region	—
ce_get_project	Get project details	project_id
ce_create_project	Create a new project	name, resource_group_id
ce_delete_project	Delete a project	project_id

Code Engine: Applications (7)

Tool	Description	Key Parameters
ce_list_applications	List applications in a project	project_id
ce_get_application	Get application details	project_id, app_name
ce_create_application	Deploy a new application	project_id, name, image, port, env_vars
ce_update_application	Update image, scaling, env	project_id, app_name, image, scale_*
ce_delete_application	Delete an application	project_id, app_name
ce_list_app_instances	List running instances (pods)	project_id, app_name
ce_get_app_logs	Get logs for an app instance	project_id, app_name, instance_name

Code Engine: Builds (7)

Tool	Description	Key Parameters
ce_list_builds	List build configurations	project_id
ce_get_build	Get build configuration details	project_id, build_name
ce_create_build	Create a build configuration	project_id, name, output_image, output_secret
ce_delete_build	Delete a build configuration	project_id, build_name
ce_list_build_runs	List build runs	project_id
ce_get_build_run	Get build run status	project_id, build_run_name
ce_create_build_run	Start a build run	project_id, build_name
ce_delete_build_run	Delete a build run	project_id, build_run_name

Code Engine: Jobs (8)

Tool	Description	Key Parameters
ce_list_jobs	List job definitions	project_id
ce_get_job	Get job definition details	project_id, job_name
ce_create_job	Create a job definition	project_id, name, image
ce_delete_job	Delete a job definition	project_id, job_name
ce_list_job_runs	List job runs	project_id, job_name (optional)
ce_get_job_run	Get job run status	project_id, job_run_name
ce_create_job_run	Submit a job run	project_id, job_name
ce_delete_job_run	Delete a job run	project_id, job_run_name

Code Engine: Secrets (4)

Tool	Description	Key Parameters
ce_list_secrets	List secrets (names + keys only)	project_id
ce_get_secret	Get secret metadata (no values)	project_id, secret_name
ce_create_secret	Create a secret	project_id, name, format, data
ce_delete_secret	Delete a secret	project_id, secret_name

Code Engine: ConfigMaps (4)

Tool	Description	Key Parameters
ce_list_config_maps	List configmaps	project_id
ce_get_config_map	Get configmap details	project_id, config_map_name
ce_create_config_map	Create a configmap	project_id, name, data
ce_delete_config_map	Delete a configmap	project_id, config_map_name

🔐 Environment Variables

• IBMCLOUD_API_KEY: IBM Cloud API key (required for Code Engine operations)
• IBMCLOUD_REGION: Default IBM Cloud region (optional, defaults to us-south)
• CONTAINER_RUNTIME: Force specific runtime (docker or podman)
• DEBUG: Enable debug logging

📋 Prerequisites

• Node.js v18 or higher
• Docker or Podman installed
• IBM Cloud CLI with Code Engine plugin (for Code Engine operations)
• IBM Cloud API key (for Code Engine operations)

👩‍💻 Development

# Run in development mode
npm run dev

# Build
npm run build

# Test manually
node build/index.js

🧪 Troubleshooting

Server Not Connecting

• Verify the path in configuration is absolute
• Check Node.js is in PATH: node --version
• Verify build output exists: ls build/index.js
• Test manually: node build/index.js

Docker/Podman Commands Failing

• Verify installation: docker --version or podman --version
• Check Docker daemon is running
• Verify permissions (add user to docker group if needed)

Code Engine Commands Failing

• Verify IBM Cloud CLI: ibmcloud --version
• Check Code Engine plugin: ibmcloud plugin list
• Verify API key is set in environment
• Test manually: ibmcloud ce project list

🛡️ Security

• Never commit API keys to version control
• Use environment variables for sensitive data
• Consider using IBM Cloud IAM for authentication
• Restrict MCP server permissions as needed

📄 License

MIT (see LICENSE)

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

👤 Author

Markus van Kempen
Email: [e-mail] | [e-mail]
Website: markusvankempen.github.io
Research | Floor 7 1/2

🙋 Support

For issues and questions:

• Check Setup Instructions and Code Engine API Reference
• Open an issue in this repository with reproduction steps and logs