MCP Google (mcp-google)

谷歌文档MCP服务器

用于Google Docs集成的MCP（模型上下文协议）服务器实现，使AI助手能够通过标准化工具与Google Docs进行交互。

特性

此MCP服务器为Google Docs操作提供了全面的工具：

• list_文档：列出Google云端硬盘中的所有Google Docs文档
• get_document：获取文档的详细内容和结构
• 创建_文档：创建新的Google Docs文档
• insert_text：在文档中的任何位置插入文本
• replace_text：在整个文档中查找和替换文本
• format_text：应用粗体、斜体或下划线格式
• insert_image：从URL插入图像
• 导出文档：导出多种格式的文档（PDF、DOCX等）
• 删除文档：删除（回收）文档

先决条件

• Python 3.13+
• 具有API访问权限的Google帐户
• 具有适当作用域的Google OAuth 2.0访问令牌

要求的Google API范围

您的OAuth令牌必须具有以下作用域：

• https://www.googleapis.com/auth/documents -用于Google Docs操作
• https://www.googleapis.com/auth/drive.file -用于文件管理

安装

方法1：直接安装

1. 克隆此存储库：

git clone 
cd mcp-google

1. 使用uv创建和激活虚拟环境：

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate     # On Windows

1. 安装依赖项：

uv pip install -e .

方法2：使用uvx（推荐用于Cursor/Claude桌面）

无需安装！直接使用：

uvx git+https://github.com/your-username/mcp-google

配置

获取Google OAuth访问令牌

您需要获得Google OAuth 2.0访问令牌。以下是几种方法：

选项1：使用Google OAuth 2.0游乐场（快速测试）

1. 首选 谷歌OAuth 2.0游乐场
2. 点击齿轮图标(⚙️) 在右上角，选中“使用自己的OAuth凭据”
3. 输入您的OAuth客户端ID和密码（从谷歌云控制台）
4. 在步骤1中，选择以下范围：

- https://www.googleapis.com/auth/documents - https://www.googleapis.com/auth/drive.file

1. 点击“授权API”
2. 在步骤2中，单击“令牌交换授权码”
3. 复制 访问令牌 （注：约1小时后过期）

选项2：使用OpenManus OAuth集成（建议用于生产环境）

如果您使用的是OpenManus平台（来自附件），它已经内置了Google OAuth集成。访问令牌是自动管理的。

选项3：创建自己的OAuth流

1. 首选 谷歌云控制台
2. 创建新项目或选择现有项目
3. 启用Google Docs API和Google Drive API
4. 创建OAuth 2.0凭据（桌面应用程序或Web应用程序）
5. 在您的应用程序中实现OAuth流
6. 存储刷新令牌以供长期访问

环境配置

1. 复制示例环境文件：

cp .env.example .env

1. 编辑 .env 并添加您的访问令牌：

GOOGLE_ACCESS_TOKEN=your_actual_access_token_here

重要：访问令牌在短时间（通常为1小时）后过期。对于生产使用，实现令牌刷新逻辑或使用像OpenManus这样的自动管理令牌的服务。

用法

运行服务器

使用以下方法之一启动MCP服务器：

# Method 1: Run directly with Python
python main.py

# Method 2: Use the installed command
mcp-google-docs

# Method 3: Run with uv (recommended)
uv run mcp-google-docs

# Method 4: Run with uvx (no installation needed)
uvx git+https://github.com/your-username/mcp-google main.py

MCP检验员测试

交互式测试您的MCP服务器：

# Using installed command
npx @modelcontextprotocol/inspector uv run mcp-google-docs

# Using Python directly
npx @modelcontextprotocol/inspector uv run python main.py

# Using uvx (from git)
npx @modelcontextprotocol/inspector uvx git+https://github.com/your-username/mcp-google

添加到Claude桌面或光标

将以下内容添加到MCP配置中：

使用本地安装：

{
  "mcpServers": {
    "google-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-google",
        "run",
        "mcp-google-docs"
      ]
    }
  }
}

使用uvx（直接来自Git-推荐）：

{
  "mcpServers": {
    "google-docs": {
      "command": "uvx",
      "args": [
        "git+https://github.com/your-username/mcp-google"
      ],
      "env": {
        "GOOGLE_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

配置文件位置：

• MacOS/光标: ~/Library/Application Support/Cursor/mcp.json
• MacOS/Claude桌面: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%/Claude/claude_desktop_config.json

可用工具

1.列表_文档

列出Google云端硬盘中的所有Google Docs文档。

参数：

• max_results （整数，可选）：要返回的最大文档数（默认值：10，最大值：1000）

退货：

{
  "files": [
    {
      "id": "document-id",
      "name": "Document Name",
      "createdTime": "2024-01-01T00:00:00Z",
      "modifiedTime": "2024-01-02T00:00:00Z",
      "webViewLink": "https://docs.google.com/document/d/..."
    }
  ],
  "count": 5,
  "message": "Successfully listed 5 documents"
}

2.获取文档

获取Google Docs文档的详细内容和结构。

参数：

• document_id （字符串，必填）：谷歌文档文档ID

退货：

{
  "documentId": "document-id",
  "title": "Document Title",
  "body": {
    "content": [...]
  },
  "message": "Successfully retrieved document: Document Title"
}

3.创建_文档

创建一个新的谷歌文档。

参数：

• title （string，必填）：新文档的标题

退货：

{
  "documentId": "new-document-id",
  "title": "New Document",
  "webViewLink": "https://docs.google.com/document/d/...",
  "message": "Successfully created document: New Document"
}

4.插入文本

在文档的指定位置插入文本。

参数：

• document_id （字符串，必填）：谷歌文档文档ID
• text （字符串，必填）：要插入的文本内容
• index （整数，可选）：插入文本的位置（默认值：1）

例子：

# Insert "Hello World" at the beginning of document
insert_text(document_id="abc123", text="Hello World\n", index=1)

5.替换文本

替换文档中出现的所有文本。

参数：

• document_id （字符串，必填）：谷歌文档文档ID
• old_text （字符串，必填）：用于查找和替换的文本
• new_text （字符串，必填）：替换文本

例子：

# Replace all "old" with "new"
replace_text(document_id="abc123", old_text="old", new_text="new")

6.格式文本

将格式应用于文档中的文本。

参数：

• document_id （字符串，必填）：谷歌文档文档ID
• start_index （整数，必填）：要格式化的文本的起始位置
• end_index （整数，必填）：要格式化的文本的结束位置
• bold （布尔值，可选）：将文本加粗
• italic （布尔值，可选）：将文本设置为斜体
• underline （布尔值，可选）：使文本带有下划线

例子：

# Make text from position 1 to 10 bold and italic
format_text(document_id="abc123", start_index=1, end_index=10, bold=True, italic=True)

7.插入图像

在文档中插入图像。

参数：

• document_id （字符串，必填）：谷歌文档文档ID
• image_url （string，必填）：图像的可公开访问的URL
• index （整数，可选）：插入图像的位置（默认值：1）

例子：

# Insert image at beginning of document
insert_image(document_id="abc123", image_url="https://example.com/image.png", index=1)

8.导出文件

将文档导出为指定格式。

参数：

• document_id （字符串，必填）：谷歌文档文档ID
• export_format （字符串，可选）：导出格式（默认：“pdf”）

- 支持：pdf、docx、odt、rtf、txt、html、epub

例子：

# Export document as PDF
export_document(document_id="abc123", export_format="pdf")

9.删除文档

删除（垃圾）Google Docs文档。

参数：

• document_id （string，必填）：要删除的Google Docs文档ID

例子：

# Delete document
delete_document(document_id="abc123")

项目结构

mcp-google/
├── main.py              # Main MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── .env.example         # Example environment variables
├── .env                 # Your actual credentials (git-ignored)
└── README.md           # This file

依赖项

• fastmcp：构建MCP服务器的框架
• httpx：用于API请求的现代HTTP客户端
• python dotenv：从.env文件加载环境变量

建筑

此MCP服务器遵循与Salesforce和Databricks服务器相同的模式：

sequenceDiagram
    participant Cursor
    participant uvx
    participant MCP as MCP Server
    participant Google as Google APIs

    Cursor->>uvx: uvx git+https://github.com/.../mcp-google
    uvx->>uvx: Clone repo & install deps
    uvx->>MCP: Run main:mcp.run()
    MCP-->>Cursor: STDIO connection ready
    
    Cursor->>MCP: list_documents
    MCP->>Google: GET /drive/v3/files
    Google-->>MCP: Document list
    MCP-->>Cursor: Formatted response

错误处理

服务器包括全面的错误处理：

• 缺少令牌：如果未设置GOOGLE_ACCESS_TOKEN，则清除错误消息
• 身份验证错误：报告令牌过期或无效作用域错误
• API错误：发现Google API错误并返回有用的消息
• 速率限制：尊重Google API费率限制

安全说明

• 永远不要承诺你的 .env 文件到版本控制
• 确保您的Google访问令牌安全
• 将刷新令牌用于生产部署
• 定期轮换您的OAuth凭据
• 考虑为服务器到服务器应用程序使用服务帐户

令牌到期

OAuth访问令牌通常在1小时后过期。用于生产用途：

1. 实现令牌刷新：使用刷新令牌自动获取新的访问令牌
2. 使用OpenManus：如果您部署了OpenManus，它会自动处理令牌刷新
3. 服务帐户：对于服务器应用程序，考虑使用Google服务帐户

与OpenManus集成

此MCP服务器可以与OpenManus平台集成（来自附件）：

1. OpenManus已经实现了Google OAuth流
2. 它自动管理访问令牌和刷新令牌
3. 这 GoogleDocsConnector OpenManus中的类可以用作参考
4. 在此MCP服务器中使用来自OpenManus的相同访问令牌

故障排除

令牌过期错误

错误: 401 Unauthorized 或令牌过期消息

解决方案：从Google OAuth Playground获取新的访问令牌或实现刷新令牌逻辑

权限不足

错误: 403 Forbidden 或范围错误

解决方案：确保您的OAuth令牌具有所需的作用域：

• https://www.googleapis.com/auth/documents
• https://www.googleapis.com/auth/drive.file

找不到文档

错误：找不到文档ID

解决方案:

• 验证文档ID是否正确
• 确保您的Google帐户可以访问该文档
• 检查文档是否被删除或移动

发展

运行测试

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 提交拉取请求

许可证

\[在此处添加您的许可证\]

相关项目

• mcp销售团队 -Salesforce MCP服务器
• mcp数据块 -\_CHMCP服务器
• OpenManus -与谷歌集成的人工智能数据分析平台

支持

对于问题和疑问：

• 检查 Google文档API文档
• 审查 Google OAuth 2.0文档
• 在此存储库中打开问题

致谢

内置：

• FastMCP -MCP服务器框架
• 谷歌文档API
• Google Drive API