bastion-k8s-mcp

Generic Model Context Protocol (MCP) server for remote Kubernetes operations via a bastion host.

Any MCP client can connect (Cursor, Claude Desktop, VS Code, custom SDK) using stdio transport.

What it does

MCP Client → bastion-k8s-mcp (local) → SSH → bastion → kubectl exec / ssh → pods & hosts

Composable tools:

| Tool | Purpose | |------|---------| | bastion_check | Short Hop1 SSH probe (reachable / latencyMs; not kubectl) | | bastion_exec | Run shell on bastion | | k8s_list_pods | List pods (kubectl get pods) | | k8s_exec | Run command in pod container | | k8s_logs | Pod stdout/stderr (kubectl logs) | | ssh_exec | SSH from bastion to remote host | | remote_read_file | Read file head/tail (mode=head\|tail) on bastion/pod/host | | remote_copy_file | Sync copy between local/bastion/pod/host (Hop1 SFTP: file/dir, skipIfComplete / totalTimeoutMs / progress) | | remote_copy_start | Async copy job — returns transferId immediately (prefer for >256MB or ETA>2min) | | remote_copy_status | Poll async copy job progress | | remote_copy_cancel | Cancel async copy job | | remote_ps | List processes on bastion/pod/host |

Async job state: ~/.agent-compose/remote-copy/jobs/<transferId>.json — see docs/REMOTE_COPY_JOB_API.md.

No business logic, no hardcoded namespaces or paths.

Quick start

Option A — npx（推荐，无需 clone/build）

Requires Node.js >= 18 only.

{
  "mcpServers": {
    "bastion-k8s": {
      "command": "npx",
      "args": ["-y", "bastion-k8s-mcp@latest"],
      "env": {
        "BASTION_HOST": "10.0.0.1",
        "BASTION_USER": "your-user"
      }
    }
  }
}

Pin a version for stability: "args": ["-y", "[email protected]"]

Option B — 本地开发

cd bastion-k8s-mcp
npm install
npm run build

MCP config uses local path:

"command": "node",
"args": ["<ABS_PATH>/bastion-k8s-mcp/dist/index.js"]

Minimal env

Only BASTION_HOST and BASTION_USER are required. Configure any SSH auth you use (key path, default ~/.ssh keys, SSH agent, and/or BASTION_PASSWORD); the client tries each until one works. If your IDE exposes an empty SSH agent, set BASTION_PASSWORD and it will be used after agent/key attempts fail.

Publishing (maintainers)

npm run build && npm test
npm publish          # or --registry for private npm

Documentation

• 使用教程（中文） — Node.js 安装、MCP 配置、Agent 实用话术
• Agent usage guide — for LLM agents after MCP handshake
• Configuration — env vars, auth, client setup
• Security — trust boundaries, credentials, namespace scope
• Contributing — dev setup, tests, lint
• Client examples — Cursor, Claude Desktop, VS Code

MCP prompts

| Prompt | Description | |--------|-------------| | tool-selection | Pick the right tool for a scenario (all ops via bastion) | | remote-debug-workflow | Standard list → read/tail → ps workflow |

Architecture

All tools use MCP client → SSH → bastion → target. There is no direct SSH from the laptop to pods/hosts. See docs/AGENT_GUIDE.md.

Development

npm test
npm run build
npm run lint

Manual integration tests (real bastion/cluster) live under scripts/manual/. Copy scripts/manual/env.example to .env.local — never commit credentials.

License

MIT