谷歌文档MCP服务器-Docker

运行Docker的配置谷歌文档MCP服务器在一个容器里。

该服务器提供模型上下文协议（MCP）工具，用于与Google Docs和Google Drive进行交互，使Claude等AI助手能够读取、写入和管理您的文档。

特性

文档创建

创建空白文档 -从头开始创建新的Google文档
从Markdown导入 -使用Google Drive API的本地markdown导入（2024年7月+），使用从markdown导入的内容创建Google文档。支持标准markdown语法，格式由谷歌的原生解析器处理。

文档操作

阅读文档 -将内容导出为文本、JSON或markdown（markdown导出使用Google Drive API的本地导出）
编辑文档 -插入、附加和删除文本
格式化文本 -应用字符和段落样式（粗体、斜体、颜色、字体、对齐方式等）
管理结构 -插入表格、分页符和图像
手柄标签 -列出并处理多标签文档
批量操作 -在单个批处理API调用中执行多个文档操作，性能提高5-10倍

列出、添加、回复、解决和删除对文档的评论

驱动器集成

列出、搜索和获取文档元数据
创建和管理文件夹
上传文件和图像
基于资源的上传 -使用共享blob存储中的资源标识符上传文件和图像（用于与其他MCP服务器集成）

先决条件

已安装Docker和Docker Compose
Google帐户
具有OAuth凭据的谷歌云项目

安装说明

步骤1：获取Google Cloud凭据

转到谷歌云控制台

创建或选择项目：

- 点击项目下拉菜单，选择“新建项目” - 命名它（例如，“谷歌文档MCP”），然后单击“创建”

启用所需的API：

- 转到“API和服务”>“库” - 搜索并启用 谷歌文档API - 搜索并启用 Google Drive API

配置OAuth同意屏幕：

- 转到“API和服务”>“OAuth同意屏幕” - 选择“外部”并单击“创建” - 填写： - 应用程序名称：例如“谷歌文档MCP服务器” - 用户支持电子邮件：您的电子邮件 - 开发人员联系人：您的电子邮件 - 点击“保存并继续” - 点击“添加或删除范围”并添加： - https://www.googleapis.com/auth/documents - https://www.googleapis.com/auth/drive.file - 点击“更新”，然后点击“保存并继续” - 将您的Google电子邮件添加为 测试用户 - 点击“保存并继续”

创建OAuth凭据：

- 转到“API和服务”>“凭据” - 点击“+创建证书”>“OAuth客户端ID” - 选择“桌面应用程序”作为应用程序类型 - 命名它（例如，“MCP Docker客户端”） - 点击“创建” - 下载JSON文件

步骤2：配置凭据

创建 credentials 此项目中的目录：

   mkdir -p credentials

复制您下载的OAuth JSON文件：

   cp ~/Downloads/client_secret_*.json credentials/credentials.json

步骤3：构建Docker镜像

docker-compose build

步骤4：使用谷歌进行身份验证（首次设置）

第一次运行服务器时，您需要向Google进行身份验证以生成令牌。身份验证使用环回OAuth流 自动端口发现.

它是如何工作的：

容器通过Docker API发现其发布的端口
OAuth回调自动重定向到发现的主机端口
无需手动配置端口

重要提示： 如果不存在，请在运行前创建一个空的token.json文件：

touch credentials/token.json

运行容器（Docker会自动分配一个临时端口）：

docker run -it --rm \
  -p 3000 \
  -v $(pwd)/credentials:/workspace/credentials \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  workspace-google-docs-mcp:latest

注：在Windows上，使用完整路径而不是 $(pwd):

docker run -it --rm ^
  -p 3000 ^
  -v C:/path/to/google-docs-mcp/credentials:/workspace/credentials ^
  -v /var/run/docker.sock:/var/run/docker.sock:ro ^
  workspace-google-docs-mcp:latest

容器将通过Docker API检测其发布的端口，并将其显示在日志中
服务器将输出一个授权URL
复制URL并在浏览器中打开
使用您的Google帐户（添加为测试用户的帐户）登录
点击“允许”授予权限
谷歌将重定向到发现的端口——容器会自动捕获这一点
您将在浏览器中看到“身份验证成功！”
这 token.json 文件将保存到您的 credentials/ 目录
按Ctrl+C停止容器

或者，使用docker compose：

docker-compose up

步骤5：运行服务器

docker-compose up -d

MCP服务器现在正在运行并准备接受连接。

Claude桌面集成

将此添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json

Docker安装

在Docker容器中运行MCP服务器。这需要装载凭据和令牌文件：

{
  "mcpServers": {
    "google-docs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "3000",
        "-v",
        "C:/path/to/google-docs-mcp/credentials:/workspace/credentials",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock:ro",
        "-v",
        "blob-storage:/mnt/blob-storage",
        "-e",
        "BLOB_STORAGE_ROOT=/mnt/blob-storage",
        "-e",
        "BLOB_STORAGE_MAX_SIZE_MB=100",
        "-e",
        "BLOB_STORAGE_TTL_HOURS=24",
        "workspace-google-docs-mcp:latest"
      ]
    }
  }
}

配置说明：

-p 3000 -临时端口绑定（Docker自动分配可用主机端口）
第一 -v mount映射您的本地 credentials/ 目录（包含两者 credentials.json 和 token.json)to /workspace/credentials/ 在集装箱内
第二 -v mount为自动端口发现提供Docker套接字访问

- 窗户： Docker桌面自动翻译 /var/run/docker.sock 到Windows命名管道 - Linux/macOS： 使用本地Docker套接字 /var/run/docker.sock - 重要提示： 确保“打开守护进程”tcp://localhost:2375Docker桌面设置中未启用“无TLS”（这是一种安全风险，不需要）

第三 -v mount为基于资源的文件上传创建共享blob存储卷（可选，仅在使用基于资源的上传功能时需要）
这 -e 标志为blob存储配置设置环境变量（可选，显示默认值）

注：调整路径(C:/path/to/google-docs-mcp/credentials)以匹配您的本地凭据目录。在Linux/macOS上，使用Unix风格的路径（例如。， /home/user/google-docs-mcp/credentials).

可选： 如果不需要基于资源的上载功能，请删除blob存储卷装载和环境变量。

使用正在运行的容器

如果您希望容器在后台运行，请使用 docker-compose up -d:

{
  "mcpServers": {
    "google-docs": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "google-docs-mcp-server",
        "uv",
        "run",
        "google-docs-mcp"
      ]
    }
  }
}

注：启动Claude Desktop之前，容器必须正在运行。

更新配置后重新启动Claude Desktop。

文件结构

.
├── Dockerfile                      # Docker image definition (dev + production)
├── docker-compose.yml              # Docker Compose for production
├── docker-compose.devcontainer.yml # Docker Compose for VS Code devcontainer
├── .devcontainer/
│   └── devcontainer.json           # VS Code devcontainer configuration
├── src/
│   └── google_docs_mcp/            # Python source code
│       ├── server.py               # Main MCP server entry point
│       ├── auth.py                 # OAuth2 authentication (loopback flow)
│       └── api/                    # API modules (documents, comments, drive)
├── tests/                          # Test files
├── credentials/                    # Your Google OAuth credentials (gitignored)
│   ├── credentials.json            # OAuth client credentials
│   └── token.json                  # OAuth access token (generated after auth)
├── pyproject.toml                  # Python project configuration
├── .gitignore                      # Git ignore rules
└── README.md                       # This file

发展

VS代码开发容器（推荐）

该项目包括VS Code的devcontainer配置：

在VS Code中打开项目
出现提示时，单击“在容器中重新打开”（或使用命令面板：“开发容器：在容器中再次打开”）
VS Code将自动构建容器并安装依赖项

devcontainer包括：

带uv包管理器的Python 3.12
Docker CLI（Docker不支持Docker）
Node.js 20和克劳德代码CLI
VS代码扩展：Python、Pylance、debugpy、Ruff、Claude Code
端口3000已转发用于OAuth环回回调

本地开发（无集装箱）

# Install dependencies
uv sync

# Run the server
uv run google-docs-mcp

# Run tests
uv run pytest

OAuth端口发现

此服务器使用Docker API自动发现其用于OAuth回调的已发布端口。这使得：

临时端口绑定 -Docker可以分配任何可用的主机端口
无端口冲突 -多个实例可以同时运行
自动配置 -无需手动设置端口

运作原理

集装箱启动 使用临时端口绑定（例如。， -p 3000)
Docker分配 可用主机端口（例如32768）
服务器发现 通过Docker API的映射（读取 /proc/self/cgroup 并查询Docker套接字）
OAuth重定向类型 使用发现的主机端口(http://localhost:32768)
身份验证成功 自动地

需求

必须挂载Docker套接字： -v /var/run/docker.sock:/var/run/docker.sock:ro
python docker 必须安装包（包含在依赖项中）

回退行为

如果Docker API不可用（套接字未安装或未在Docker中运行）：

回退到默认端口3000
将警告记录到stderr
使用静态端口正常继续

故障排除

“Docker API不可用”或“连接中止”错误：

*带Docker桌面的Windows：*

确保Docker桌面正在运行并完全启动
在Docker桌面设置中→ 常规，验证“暴露后台程序tcp://localhost:2375没有TLS”是关闭（未选中）
插座安装 -v /var/run/docker.sock:/var/run/docker.sock:ro 应该自动工作（Docker Desktop翻译它）
如果错误仍然存在，请尝试重新启动Docker Desktop
作为一种解决方法，您可以省略Docker套接字挂载——服务器将回退到端口3000（但您需要使用 -p 3000:3000 而不是 -p 3000)

*Linux/macOS：*

确保Docker套接字已安装在您的配置中
检查套接字权限： ls -l /var/run/docker.sock
将您的用户添加到docker组： sudo usermod -aG docker $USER （然后注销并重新登录）

“未找到端口映射”警告：

验证端口是否在docker run/compose配置中发布
请检查： docker port

身份验证仍然失败：

检查容器日志： docker logs
在Google Cloud控制台中验证OAuth凭据
确保重定向URI与Google期望的一致

命令

命令	描述
`docker-compose build`	构建Docker镜像
`docker-compose up -d`	在后台启动服务器
`docker-compose down`	停止服务器
`docker-compose logs -f`	查看服务器日志
`docker-compose --profile auth run --rm auth`	以交互方式运行身份验证服务

基于资源的文件上传

此MCP服务器与 mcp_maped_resource_lib 支持 基于资源的文件上传这使得通过共享的Docker卷在多个MCP服务器之间实现高效的文件共享。

为什么要使用基于资源的上传？

传统的MCP文件传输需要将文件编码为base64，并通过MCP协议传递，这对于大文件来说效率低下。使用基于资源的上传：

其他MCP服务器 将文件上传到共享blob存储卷并返回资源标识符（例如。， blob://1733437200-a3f9d8c2b1e4f6a7.png)
此服务器 可以通过资源标识符直接访问这些文件并将其上传到Google Drive
无文件数据 通过MCP协议传输，仅传输小资源标识符

可用的基于资源的工具

upload_image_to_drive_from_resource -使用资源ID将图像上传到驱动器
upload_file_to_drive_from_resource -使用资源ID将任何文件上传到驱动器
insert_image_from_resource -使用资源ID将图像插入文档

基于资源的上传设置

1.配置Blob存储卷

为您的blob存储添加共享卷 docker-compose.yml:

services:
  google-docs-mcp:
    # ... existing config ...
    volumes:
      - ./credentials:/workspace/credentials
      - blob-storage:/mnt/blob-storage  # Add this line
    environment:
      - PYTHONUNBUFFERED=1
      - BLOB_STORAGE_ROOT=/mnt/blob-storage  # Required
      - BLOB_STORAGE_MAX_SIZE_MB=100         # Optional: max file size (default: 100)
      - BLOB_STORAGE_TTL_HOURS=24            # Optional: time-to-live (default: 24)

volumes:
  blob-storage:
    driver: local

配置选项：

BLOB_STORAGE_ROOT - 必需blob存储目录的路径
BLOB_STORAGE_MAX_SIZE_MB -可选。最大文件大小（MB）（默认值：100）
BLOB_STORAGE_TTL_HOURS -可选。blob的生存时间（默认值：24小时）。比这更老的泡泡会被自动清理干净。

2.更新Claude桌面配置

使用基于资源的上传时，请更新您的 claude_desktop_config.json 要装载blob存储卷，请执行以下操作：

{
  "mcpServers": {
    "google-docs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "3000:3000",
        "-v",
        "C:/path/to/google-docs-mcp/credentials:/workspace/credentials",
        "-v",
        "blob-storage:/mnt/blob-storage",
        "-e",
        "BLOB_STORAGE_ROOT=/mnt/blob-storage",
        "-e",
        "BLOB_STORAGE_MAX_SIZE_MB=100",
        "-e",
        "BLOB_STORAGE_TTL_HOURS=24",
        "workspace-google-docs-mcp:latest"
      ]
    }
  }
}

注：替换 C:/path/to/google-docs-mcp/credentials 使用您的实际凭据路径。在Linux/macOS上，使用Unix风格的路径。

配置：

调整 BLOB_STORAGE_MAX_SIZE_MB 设置最大文件大小（MB）
调整 BLOB_STORAGE_TTL_HOURS 控制自动清理前保留斑点的时间

3.与其他MCP服务器共享卷

其他MCP服务器可以使用相同的卷。配置示例：

{
  "mcpServers": {
    "google-docs": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "3000:3000",
        "-v", "C:/path/to/google-docs-mcp/credentials:/workspace/credentials",
        "-v", "blob-storage:/mnt/blob-storage",
        "-e", "BLOB_STORAGE_ROOT=/mnt/blob-storage",
        "-e", "BLOB_STORAGE_MAX_SIZE_MB=100",
        "-e", "BLOB_STORAGE_TTL_HOURS=24",
        "workspace-google-docs-mcp:latest"
      ]
    },
    "other-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "blob-storage:/mnt/blob-storage:ro",
        "other-mcp-server:latest"
      ]
    }
  }
}

重要提示： 卷名(blob-storage)所有需要共享资源的MCP服务器之间必须保持一致。

示例用法

使用另一个具有blob上传功能的MCP服务器：

其他MCP服务器 将文件上传到blob存储：

   User: Upload this image to blob storage
   Other Server: Uploaded! Resource ID: blob://1733437200-a3f9d8c2b1e4f6a7.png

此服务器 使用资源ID上传到Google云端硬盘：

   User: Upload that image to my Google Drive using resource blob://1733437200-a3f9d8c2b1e4f6a7.png
   Google Docs Server: Successfully uploaded image "photo.png" from resource blob://1733437200-a3f9d8c2b1e4f6a7.png

资源ID格式

资源标识符遵循以下模式： blob://TIMESTAMP-HASH.EXT

TIMESTAMP -上传文件时的Unix时间戳
HASH -SHA256哈希（截断）用于唯一性
EXT -原始文件扩展名

例子： blob://1733437200-a3f9d8c2b1e4f6a7.png

批量操作

这 bulk_update_google_doc 该工具允许您在单个批处理API调用中执行多个文档操作，从而提供 5-10倍的性能提升 通过单独的工具调用。

为什么要使用批量操作？

当对文档进行多次更改（格式化、插入内容、添加表等）时，每个单独的工具调用都需要到Google的API进行单独的网络往返。这会产生显著的延迟：

之前（个人通话）：

10次格式化操作=10次API调用=5-10秒

之后（批量操作）：

10次格式化操作=1次API批处理调用=约0.5-1秒

支持的操作

批量工具支持所有文档操作：

insert_text -在特定索引处插入文本
delete_range -删除某个范围内的内容
应用程序_文本_样式 -应用字符级格式（粗体、斜体、颜色等）
应用_段落_样式 -应用段落级格式（对齐、标题、间距等）
insert_table -插入表格
insert_page_break -插入分页符
insert_image_from_url -从URL插入图像

示例用法

以下是在单个API调用中创建具有标题、简介、表格和样式文本的格式化文档的示例：

{
  "document_id": "your-document-id-here",
  "operations": [
    {
      "type": "insert_text",
      "text": "Project Status Report\n\n",
      "index": 1
    },
    {
      "type": "apply_paragraph_style",
      "start_index": 1,
      "end_index": 23,
      "named_style_type": "HEADING_1",
      "alignment": "CENTER"
    },
    {
      "type": "insert_text",
      "text": "Executive Summary\n\n",
      "index": 23
    },
    {
      "type": "apply_paragraph_style",
      "start_index": 23,
      "end_index": 42,
      "named_style_type": "HEADING_2"
    },
    {
      "type": "insert_text",
      "text": "This report provides an overview of project progress and key metrics.\n\n",
      "index": 42
    },
    {
      "type": "insert_text",
      "text": "Key Metrics\n\n",
      "index": 113
    },
    {
      "type": "apply_paragraph_style",
      "start_index": 113,
      "end_index": 126,
      "named_style_type": "HEADING_2"
    },
    {
      "type": "insert_table",
      "rows": 4,
      "columns": 3,
      "index": 126
    },
    {
      "type": "insert_text",
      "text": "\n\nConclusion\n",
      "index": 127
    },
    {
      "type": "apply_text_style",
      "text_to_find": "Conclusion",
      "match_instance": 1,
      "bold": true,
      "font_size": 14
    }
  ]
}

操作参数

每个操作都是一个字典 type 现场和操作特定参数：

insert_text

text （string）：要插入的文本
index （整数）：插入位置（从1开始）
tab_id （字符串，可选）：多标签文档的标签ID

delete_range

start_index （整数）：范围的开始（从1开始，包括1）
end_index （整数）：范围结束（从1开始，不包括在内）
tab_id （字符串，可选）：选项卡ID

应用程序_文本_样式

距离瞄准（选择一个）：

start_index 和 end_index （整数）：直接范围规范
text_to_find （字符串）和 match_instance （整数）：查找特定文本

样式属性：

bold, italic, underline, strikethrough （布尔值）
font_size （浮点数）：字体大小（以点为单位）
font_family （string）：字体名称（例如“Arial”、“Times New Roman”）
foreground_color, background_color （字符串）：十六进制颜色（例如，“#FF0000”）
link_url （字符串）：超链接的URL

应用_段落_样式

距离瞄准（选择一个）：

start_index 和 end_index （整数）：直接范围规范
text_to_find （字符串）和 match_instance （整数）：查找文本，格式化其段落
index_within_paragraph （整数）：设置包含此索引的段落格式

样式属性：

alignment （字符串）：“开始”、“结束”、“中心”、“已调整”
indent_start, indent_end （浮点数）：缩进点数
space_above, space_below （浮动）：点间距
named_style_type （字符串）：“NORMAL_TEXT”、“HEADING_1”到“HEADING_6”、“标题”、“副标题”
keep_with_next （boolean）：将段落与下一个保持一致

insert_table

rows （整数）：行数
columns （整数）：列数
index （整数）：要插入的位置（从1开始）

insert_page_break

index （整数）：要插入的位置（从1开始）

insert_image_from_url

image_url （string）：可公开访问的图像URL
index （整数）：要插入的位置（从1开始）
width, height （浮动，可选）：以点为单位的尺寸

局限性

每次调用最多500次操作（对于Google API，自动分批为50组）
操作按照提供的顺序执行
在执行任何操作之前，所有操作都必须有效（快速失败验证）

最佳性能提示

集团相关业务：在一次批量调用中合并对文档的所有更改
尽可能使用基于索引的定位：文本查找操作需要先获取文档
订单事项：组织操作以考虑索引更改（例如，在对文本应用格式之前插入文本）

Markdown支持

该服务器使用Google Drive API的原生markdown导入/导出（自2024年7月起提供），该功能通过Google的官方解析器提供可靠的转换。

已知限制

markdown导出中的图像：图像导出为base64数据URL（已知的谷歌限制）。要共享文档，请使用原始的Google Docs文件。
选项卡支持：markdown导出API导出整个文档。不支持单个选项卡导出-如果您指定了tab_id，您将收到警告，整个文档将被导出。
转换保真度：格式化质量取决于谷歌的实施。复杂的Google Docs功能可能没有精确的降价功能。
API要求：除了Google Docs API外，还需要Google Drive API访问权限（在安装过程中应启用这两项功能）。

安全须知

永不承诺 credentials.json 或 token.json 到版本控制
这 .gitignore 文件被配置为排除这些文件
将这些文件视为密码-它们授予访问您的Google帐户的权限
token.json文件允许服务器访问您的Google帐户，而无需重新验证

故障排除

“未找到credentials.json”错误：

确保您已放置 credentials.json 在 credentials/ 目录
检查文件是否命名准确 credentials.json

身份验证失败：

验证您在Google Cloud Console中以测试用户身份添加了电子邮件
确保您同时启用Google Docs API和Google Drive API

Docker容器无法启动：

检查两者 credentials.json 和 token.json 存在于 credentials/
跑 docker-compose logs 查看错误消息

Claude Desktop显示“连接失败”：

确保容器正在运行： docker-compose ps
验证容器名称是否为 google-docs-mcp-server
尝试重新启动Claude Desktop

许可证

此Docker配置是在MIT许可证下提供的。底层谷歌文档mcp 服务器是单独授权的。

Google Docs MCP Docker

快速接入

详细介绍

谷歌文档MCP服务器-Docker

特性

文档创建

文档操作

评论

驱动器集成

先决条件

安装说明

步骤1：获取Google Cloud凭据

步骤2：配置凭据

步骤3：构建Docker镜像

步骤4：使用谷歌进行身份验证（首次设置）

步骤5：运行服务器

Claude桌面集成

Docker安装

使用正在运行的容器

文件结构

发展

VS代码开发容器（推荐）

本地开发（无集装箱）

OAuth端口发现

运作原理

需求

回退行为

故障排除

命令

基于资源的文件上传

为什么要使用基于资源的上传？

可用的基于资源的工具

基于资源的上传设置

1.配置Blob存储卷

2.更新Claude桌面配置

3.与其他MCP服务器共享卷

示例用法

资源ID格式

批量操作

为什么要使用批量操作？

支持的操作

示例用法

操作参数

insert_text

delete_range

应用程序_文本_样式

应用_段落_样式

insert_table

insert_page_break

insert_image_from_url

局限性

最佳性能提示

Markdown支持

已知限制

安全须知

故障排除

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP