ksyun-mcp-server 0.2.2

MCP Server for Kingsoft Cloud (Ksyun) Python SDK

Ksyun MCP Server

MCP Server for Kingsoft Cloud (Ksyun) Python SDK — 让 LLM 直接调用金山云 API。

功能

• ksyun_api — 调用任意金山云 API
• ksyun_list_services — 列出所有可用服务及版本
• ksyun_list_actions — 列出指定服务版本的 API Action 及参数
• ksyun_audit_query — 查询审计日志
• ksyun://services 资源 — 浏览所有服务/版本/Action 摘要
• ksyun://audit/recent 资源 — 最近 10 条审计记录

大响应自动分页：MCP 协议的 structuredContent 输出有约 50KB 大小限制。当 API 返回数据超过 40KB 时，ksyun_api 会自动缓存完整响应并返回第一批数据，同时在 _meta 中附加 next_marker。LLM 只需再次调用同一 API 并传入 page_marker="<next_marker>" 即可获取下一批数据，直到所有数据返回完毕。缓存有效期为 10 分钟。

安装

从 PyPI 安装（推荐）

pip install ksyun-mcp-server

SDK (kingsoftcloud-sdk-python) 会作为依赖自动安装。

从源码安装（开发用）

cd ksyun-mcp-server
pip install -e ".[dev]"

更新

已安装的 MCP Server 更新到最新版本后，需要重启 MCP 客户端（Claude Desktop / Cursor / VS Code 等）才能生效。

从压缩包安装的更新

先在项目目录下构建压缩包：

cd ksyun-mcp-server
pip install build
python -m build

构建产物在 dist/ 目录下，用新版本的压缩包重新安装即可：

pip install dist/ksyun_mcp_server-0.2.2.tar.gz

也可以指定 .whl 文件：pip install dist/ksyun_mcp_server-0.2.2-py3-none-any.whl

从源码安装的更新

如果是可编辑安装（pip install -e），拉取最新代码后即自动生效：

cd ksyun-mcp-server
git pull
# 无需重新 pip install，-e 模式下代码变更即时生效

如果是非可编辑安装，重新执行安装命令：

cd ksyun-mcp-server
pip install ".[dev]"

重启 MCP 客户端

客户端	重启方式
Claude Desktop	完全退出应用后重新打开
Cursor	重新加载窗口（Cmd+Shift+P → Reload Window）
VS Code	重新加载窗口（Cmd+Shift+P → Reload Window）

配置

通过环境变量或 .env 文件配置（二选一）：

方式一：环境变量（推荐，无需 .env 文件）

在启动命令的 env 字段中直接传入凭证，无需创建 .env 文件：

{
  "mcpServers": {
    "ksyun": {
      "command": "ksyun-mcp-server",
      "env": {
        "KSYUN_ACCESS_KEY_ID": "your_ak",
        "KSYUN_SECRET_ACCESS_KEY": "your_sk",
        "KSYUN_REGION": "cn-beijing-6"
      }
    }
  }
}

方式二：.env 文件

复制 .env.example 为 .env 并填入凭证：

cp .env.example .env

环境变量	必填	默认值	说明
KSYUN_ACCESS_KEY_ID	✅		金山云 AccessKey ID
KSYUN_SECRET_ACCESS_KEY	✅		金山云 Secret AccessKey
KSYUN_REGION		cn-beijing-6	默认地域
KSYUN_AUDIT_BACKEND		file	审计后端：file / sqlite
KSYUN_AUDIT_DIR		~/.ksyun-mcp	审计日志目录
KSYUN_AUDIT_REDACT_FIELDS		password,secret,token,...	脱敏字段名
KSYUN_SDK_PATH		自动检测	SDK 路径（一般无需设置）

在各工具中使用

Claude Desktop

编辑 claude_desktop_config.json（路径：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "ksyun": {
      "command": "ksyun-mcp-server",
      "env": {
        "KSYUN_ACCESS_KEY_ID": "your_ak",
        "KSYUN_SECRET_ACCESS_KEY": "your_sk",
        "KSYUN_REGION": "cn-beijing-6"
      }
    }
  }
}

如果 ksyun-mcp-server 不在 PATH 中，将 command 改为 Python 解释器的完整路径：

"command": "C:\\Users\\you\\.venv\\Scripts\\ksyun-mcp-server.exe"

Cursor

编辑 ~/.cursor/mcp.json 或项目目录下 .cursor/mcp.json：

{
  "mcpServers": {
    "ksyun": {
      "command": "ksyun-mcp-server",
      "env": {
        "KSYUN_ACCESS_KEY_ID": "your_ak",
        "KSYUN_SECRET_ACCESS_KEY": "your_sk",
        "KSYUN_REGION": "cn-beijing-6"
      }
    }
  }
}

VS Code (Copilot / Continue)

在 VS Code settings.json 中：

{
  "mcp.servers": {
    "ksyun": {
      "command": "ksyun-mcp-server",
      "env": {
        "KSYUN_ACCESS_KEY_ID": "your_ak",
        "KSYUN_SECRET_ACCESS_KEY": "your_sk",
        "KSYUN_REGION": "cn-beijing-6"
      }
    }
  }
}

任意支持 MCP 的工具

只要工具支持 stdio 传输的 MCP Server，配置模式一致：

字段	值
command	ksyun-mcp-server
transport	stdio（默认，无需指定）
env	KSYUN_ACCESS_KEY_ID + KSYUN_SECRET_ACCESS_KEY（必填），其余可选

打包与发布

本地构建

cd ksyun-mcp-server
pip install build
python -m build

构建产物在 dist/ 目录下：ksyun_mcp_server-0.2.2-py3-none-any.whl 和 ksyun_mcp_server-0.2.2.tar.gz。

发布到 PyPI

pip install twine
twine upload dist/*

需要 PyPI API Token，在 ~/.pypirc 或环境变量 TWINE_PASSWORD 中配置。

发布到 TestPyPI（测试用）

twine upload --repository testpypi dist/*

用户安装方式

发布后，用户只需一行命令即可安装使用：

pip install ksyun-mcp-server

然后在任意 MCP 客户端中配置 "command": "ksyun-mcp-server" 即可。

更新记录

v0.2.2

• 修复 _parse_client_py 潜在 bug：多数投票可能在比较遍历之后改变 content_type 默认值，导致 form 类型的 action 被遗漏而错误继承 JSON 默认值。重构为先收集所有 action 的 content_type，再进行多数投票，最后用最终默认值过滤 action_content_types 字典
• 更新文档：README "打包与发布" 和 "更新" 部分的文件名引用从 v0.2.0 更新到 v0.2.2

v0.2.1

• 修复参数传递问题：LLM 经常将 API 参数扁平化到顶层（如 {"service":"vpc", "SecurityGroupId":"xxx"} 而非 {"service":"vpc", "params":{"SecurityGroupId":"xxx"}}），FastMCP 的 Pydantic 模型默认静默丢弃多余字段导致 params={}。通过 monkey-patch ArgModelBase（extra="allow" + 扩展 model_dump_one_level）自动将顶层多余字段合并到 params 字典中
• 增强 docstring：在工具描述中说明参数嵌套规则，并提示扁平化参数也会被自动收集
• 参数值类型转换：调用 SDK 前自动将所有 params 值转为字符串，兼容 LLM 传入的整数等非字符串类型
• 空参数警告：当 params 为空但 action 要求必填参数时记录 warning 日志，便于排查

v0.2.0

• 新增大响应自动分页：当 API 返回数据超过 40KB 时，ksyun_api 会自动缓存完整响应并分批返回，通过 _meta.next_marker 和 page_marker 参数实现逐页获取，确保数据不丢失（缓存有效期 10 分钟）
• 修复：ksyun_api 工具参数名从 _marker 改为 page_marker，解决 FastMCP 不允许下划线开头参数的 InvalidSignature 错误
• 移除：删除无效的 ksyun_max_response_bytes 配置项（MCP 框架硬限制无法通过配置绕过）

v0.1.0

• 初始版本
• 支持 ksyun_api、ksyun_list_services、ksyun_list_actions、ksyun_audit_query 工具
• 支持 ksyun://services、ksyun://audit/recent 资源
• 审计日志支持 file / sqlite 两种后端，敏感字段自动脱敏

审计

所有通过 MCP Server 发起的 API 调用都会自动记录审计日志，包含：

• 时间戳、服务名、版本、Action、地域
• 请求参数（敏感字段自动脱敏）
• 调用状态（success/error）、错误信息、RequestId
• 调用耗时（ms）

使用 ksyun_audit_query 工具或 ksyun://audit/recent 资源查看审计记录。

License

Apache-2.0