内容
# gslide-mcp
一个Python MCP服务器，用于公开用于构建和编辑Google Slides演示文稿的工具。它封装了[gslides-api](https://pypi.org/project/gslides-api/)库，并在其基础上添加了MCP工具：支持markdown的文本编写、幻灯片截图、跨演示文稿复制，以及一个模板库工作流程，允许您从任意多个源演示文稿中组装新的演示文稿。
## 为什么存在
Google Slides REST API及其Python客户端表达能力强但过于冗长 — 单个格式化文本更新需要五个嵌套请求字典。此服务器预先组合了最常见的操作，变成可用的MCP工具，以便语言模型可以构建精致的演示文稿，而无需在每次会话中重建样板。一个小型语义快捷方式集（`swap_client`、`fetch_logo_by_domain`、`assemble_from_template`）涵盖了代理风格演示文稿工作的繁琐部分。
## 状态
早期发布。API表面可能在小版本之间发生变化。欢迎贡献。不隶属于或获得Google认可。
## 安装
需要Python 3.10或更新版本。
```sh
git clone https://github.com/jemmanuele/gslide-mcp.git
cd gslide-mcp
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -e .
```
入口点`gslides-mcp`现在位于venv中。
## 首次运行设置（OAuth）
完整演练：[docs/oauth-setup.md](docs/oauth-setup.md)
三步精简：
1. 在[Google Cloud Console](https://console.cloud.google.com)中，创建一个**桌面应用程序** OAuth 2.0客户端ID，并启用Slides API和Drive API。
2. 下载客户端密钥JSON文件，重命名为`credentials.json`，并保存到`~/.gslides-mcp/creds/credentials.json`。
3. 第一个MCP工具调用会打开一个浏览器标签页，用于Google许可。批准后，`token.json`写入凭证文件旁边（模式`0o600`），并从那时起重复使用，并自动刷新。
所需OAuth范围：
```
https://www.googleapis.com/auth/presentations
https://www.googleapis.com/auth/drive
```
要将凭证存储在`~/.gslides-mcp/creds/`以外的目录中，请在启动服务器之前将`GSLIDES_MCP_CRED_DIR`设置为所需目录。
## 连接到客户端
将服务器添加到您的Claude Desktop或Claude Code MCP配置中：
```json
{
"mcpServers": {
"gslides": {
"command": "gslides-mcp"
}
}
}
```
如果入口点不在您的系统PATH中，请使用venv二进制文件的完整路径，例如`"/path/to/venv/bin/gslides-mcp"`。
在客户端外部进行调试时，直接运行服务器：
```sh
python -m gslides_mcp.server
```
## 工具概述
| 分组 | 工具 | 功能 |
|-------|------|--------------|
| **演示文稿** | `create_presentation` | 创建新的空白演示文稿；返回 `{presentation_id, url}` |
| | `clone_deck` | 通过Drive复制现有演示文稿 |
| | `list_slides` | 列出带有索引、对象ID和摘要的幻灯片 |
| | `inspect_slide` | 检查幻灯片上的所有元素（可选递归） |
| | `find_elements` | 按类型、替代标题或文本内容搜索元素 |
| | `export_pres` | 导出到本地 `.pptx` 或 `.pdf` |
| | `batch_apply` | 未支持操作的原始 `batchUpdate` 出口 |
| **幻灯片** | `create_slide` | 在指定位置插入新幻灯片 |
| | `duplicate_slide` | 在同一演示文稿中复制幻灯片 |
| | `move_slide` | 重新排序幻灯片 |
| | `delete_slides` | 删除一个或多个幻灯片 |
| | `set_background` | 设置幻灯片背景颜色（纯色十六进制） |
| **形状** | `create_shape` | 插入形状 |
| | `insert_image` | 通过URL插入图像 |
| | `set_fill` | 设置形状的填充颜色 |
| | `set_outline` | 设置形状的轮廓 |
| **内容** | `write_text_markdown` | 通过gslides-api的markdown编写器一次性写入粗体/斜体/项目符号 |
| | `batch_write_markdown` | `write_text_markdown`的批量版本（多元素更新速度快约N倍） |
| | `set_text` | 在形状上设置纯文本 |
| | `style_text` | 对范围应用文本样式（字体、大小、颜色） |
| | `replace_text` | 在幻灯片或演示文稿中查找和替换文本 |
| **布局** | `transform_element` | 移动元素（绝对或相对pt） |
| | `zorder` | 更改元素堆叠顺序 |
| | `duplicate_element` | 在幻灯片中复制元素 |
| | `delete_elements` | 删除一个或多个元素 |
| **质量保证** | `screenshot` | 捕获幻灯片为内联图像 |
| | `screenshot_range` | 捕获一系列幻灯片 |
| | `overlap_check` | 检测幻灯片上的重叠元素 |
| **跨演示文稿** | `copy_slide_cross_deck` | 将幻灯片从一个演示文稿复制到另一个（需要Apps Script - 参见下文） |
| | `cross_deck_ping` | 健康检查Apps Script网页应用 |
| **语义** | `swap_client` | 克隆演示文稿并重新品牌化（标志交换，名称替换） |
| **资产** | `fetch_logo_by_domain` | 通过域名解析公共标志URL |
| **库** | `summarize_deck` | 为单个演示文稿构建结构化幻灯片索引 |
| | `build_template_library` | 将多个演示文稿汇总到可重用的JSON注册表中 |
| | `assemble_from_template` | 从跨演示文稿的精选幻灯片组装新演示文稿 |
## 可选：通过Apps Script进行跨演示文稿复制
`copy_slide_cross_deck`和`assemble_from_template`通过一个小的Google Apps Script网页应用路由，因为Slides REST API没有跨演示文稿复制端点。
设置指南：[docs/appscript-setup.md](docs/appscript-setup.md)
部署后，将网页应用URL保存到`~/.gslides-mcp/appscript_url`（一行，无引号）或在环境中设置`GSLIDES_MCP_APPSCRIPT_URL`。如果未配置此选项，则这两个工具会引发带有设置说明的描述性错误。
## 可选：logo.dev用于`fetch_logo_by_domain`
`fetch_logo_by_domain`默认情况下会尝试Wikipedia Commons，然后是Brandfetch CDN，然后是Google favicon备用方案。要启用[logo.dev](https://logo.dev)源作为附加候选：
```sh
export GSLIDES_MCP_LOGODEV_TOKEN=your_token_here
```
如果未设置此变量，则logo.dev完全跳过，备用链仍会产生可用的URL。
## 模板库工作流程
参见[docs/template-library.md](docs/template-library.md)获取完整演练和[examples/template_library_workflow.md](examples/template_library_workflow.md)获取具体示例。
简而言之：`build_template_library`将演示文稿ID列表摄入JSON注册表，您审查并注释它，然后`assemble_from_template`将您选择的幻灯片拉入新演示文稿，按您指定的顺序。
## 项目布局
```
gslide-mcp/
├── README.md
├── LICENSE MIT许可证
├── pyproject.toml
├── appscript/
│ └── cross_deck_copy.gs 用于跨演示文稿复制的Apps Script网页应用
├── docs/
│ ├── oauth-setup.md Google OAuth设置演练
│ ├── appscript-setup.md Apps Script部署指南
│ └── template-library.md 模板库工作流程
├── examples/
│ └── template_library_workflow.md 示例工作流程
└── src/gslides_mcp/
├── server.py MCP入口点
├── auth.py OAuth + 服务客户端
├── app.py MCP应用程序实例
├── util.py 共享帮助程序
└── tools/
├── deck.py
├── slides.py
├── shapes.py
├── content.py
├── layout.py
├── qa.py
├── cross_deck.py
├── semantic.py
├── assets.py
└── library.py
```
## 贡献
欢迎在https://github.com/jemmanuele/gslide-mcp/issues提交错误报告和拉取请求。
## 许可证
MIT。参见[LICENSE](LICENSE)。
