npm package: @osulivan/google-docs-mcp
Description: Google Docs MCP Server - 通过 MCP 协议操作 Google 文档
Latest version: 1.0.8

# Google Docs MCP Server

通过 MCP (Model Context Protocol) 协议操作 Google 文档的 Server，支持 AI Agent 直接读写 Google 文档。

## 功能特性

- 📄 **创建文档** - 快速创建新的 Google 文档
- 📖 **读取文档** - 获取文档内容和结构
- ✏️ **编辑文档** - 插入、替换、删除文本
- 🎨 **格式化** - 支持加粗、斜体、下划线、字体大小、颜色
- 📊 **插入表格** - 在文档中添加表格
- 🔍 **搜索文档** - 搜索 Google Drive 中的文档
- 📝 **修改标题** - 修改文档标题（v1.0.6+）

## 快速开始

### 第一步：配置 Google Cloud

#### 1. 创建项目并启用 API

1. 访问 [Google Cloud Console](https://console.cloud.google.com/)
2. 创建新项目或选择现有项目
3. 启用 API：
   - [Google Docs API](https://console.cloud.google.com/apis/library/docs.googleapis.com)
   - [Google Drive API](https://console.cloud.google.com/apis/library/drive.googleapis.com)

#### 2. 配置 OAuth 同意屏幕

1. 进入 **API 和服务 > [OAuth 同意屏幕](https://console.cloud.google.com/apis/credentials/consent)**
2. 选择用户类型：
   - **外部**：任何人都可以使用（适合个人用户）
   - **内部**：仅限组织内部使用（需要 Google Workspace）
3. 填写应用信息：
   - **应用名称**：Google Docs MCP（或任意名称）
   - **用户支持邮箱**：你的邮箱
   - **开发者联系邮箱**：你的邮箱
4. 点击**保存并继续**
5. 添加权限范围（Scopes）：
   - 点击 **添加或移除范围**
   - 搜索并选择以下权限：
     - `https://www.googleapis.com/auth/documents`（Google Docs 完全访问）
     - `https://www.googleapis.com/auth/drive`（Google Drive 完全访问）
   - 点击 **更新**，然后 **保存并继续**
6. 添加测试用户（如果是外部应用）：
   - 点击 **添加用户**
   - 输入你的 Google 邮箱
   - 点击 **保存并继续**
7. 点击**返回信息中心**

#### 3. 创建 OAuth 2.0 凭据

1. 进入 **API 和服务 > [凭据](https://console.cloud.google.com/apis/credentials)**
2. 点击 **创建凭据 > OAuth 2.0 客户端 ID**
3. 应用类型选择 **桌面应用**
4. 名称填写 **Google Docs MCP**
5. 点击 **创建**
6. 下载 `client_secret.json`（记录其中的 `client_id` 和 `client_secret`）

### 第二步：获取 Refresh Token

运行以下命令，按提示输入 Client ID 和 Client Secret：

```bash
npx @osulivan/google-docs-mcp --token
```

执行流程：
1. 输入 Client ID
2. 输入 Client Secret
3. 浏览器会自动打开 Google 授权页面（或复制链接到浏览器）
4. 登录 Google 账号并点击"允许"
5. 复制浏览器地址栏中的授权码
6. 粘贴授权码到终端
7. 获得 `REFRESH_TOKEN`，保存好这个值

### 第三步：配置 MCP Client

将以下配置添加到对应的 AI 工具中：

#### Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@osulivan/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "你的-client-id",
        "GOOGLE_CLIENT_SECRET": "你的-client-secret",
        "GOOGLE_REFRESH_TOKEN": "你的-refresh-token"
      }
    }
  }
}
```

#### Cursor

编辑 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@osulivan/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "你的-client-id",
        "GOOGLE_CLIENT_SECRET": "你的-client-secret",
        "GOOGLE_REFRESH_TOKEN": "你的-refresh-token"
      }
    }
  }
}
```

#### Trae

编辑 `~/.trae/mcp.json`：

```json
{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@osulivan/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "你的-client-id",
        "GOOGLE_CLIENT_SECRET": "你的-client-secret",
        "GOOGLE_REFRESH_TOKEN": "你的-refresh-token"
      }
    }
  }
}
```

### 第四步：重启 AI 工具

重启 Claude/Cursor/Trae 后，AI 就可以使用 Google Docs 工具了！

## 使用示例

### 创建文档

```
帮我创建一个名为"项目计划"的 Google 文档
```

### 读取文档

```
请读取这个文档的内容：https://docs.google.com/document/d/DOCUMENT_ID/edit
```

### 编辑文档

```
在文档 DOCUMENT_ID 的末尾添加："会议时间：明天下午 2 点"
```

### 格式化文本

```
将文档 DOCUMENT_ID 中第 1-10 个字符设置为加粗
```

### 搜索文档

```
搜索标题包含"会议"的所有文档
```

### 修改文档标题

```
将文档 DOCUMENT_ID 的标题改为"新的文档标题"
```

## CLI 命令

```bash
# 启动 MCP Server（stdio 模式）
npx @osulivan/google-docs-mcp

# 获取 Refresh Token
npx @osulivan/google-docs-mcp --token

# 显示帮助
npx @osulivan/google-docs-mcp --help
```

## 可用工具

| 工具名 | 描述 | 参数 |
|--------|------|------|
| `docs_create` | 创建文档 | `title: string` |
| `docs_get` | 获取文档 | `documentId: string` |
| `docs_insert_text` | 插入文本 | `documentId, text, index?` |
| `docs_replace_text` | 替换文本 | `documentId, text, newText` |
| `docs_delete_text` | 删除文本 | `documentId, startIndex, endIndex` |
| `docs_format_text` | 格式化文本 | `documentId, startIndex, endIndex, bold?, italic?, underline?, fontSize?, foregroundColor?` |
| `docs_insert_table` | 插入表格 | `documentId, rows, columns, index?` |
| `docs_search` | 搜索文档 | `query?, pageSize?` |
| `docs_update_title` | 修改文档标题 | `documentId, newTitle` |

## 环境变量

| 变量名 | 说明 | 必需 |
|--------|------|------|
| `GOOGLE_CLIENT_ID` | Google OAuth Client ID | ✅ |
| `GOOGLE_CLIENT_SECRET` | Google OAuth Client Secret | ✅ |
| `GOOGLE_REFRESH_TOKEN` | Google OAuth Refresh Token（长期有效） | ✅ |

## 常见问题

### Token 会过期吗？

**不会**。`GOOGLE_REFRESH_TOKEN` 是长期有效的，配置一次即可长期使用。

- `GOOGLE_REFRESH_TOKEN`：长期有效（除非用户撤销授权）
- Access Token：1 小时过期，但 MCP Server 会自动刷新，用户无感知

### 什么情况下需要重新获取 Refresh Token？

| 情况 | 说明 |
|------|------|
| 首次使用 | 需要获取一次 |
| 撤销授权 | 用户在 Google 账号设置中撤销了应用权限 |
| 长期未使用 | 6 个月以上未使用，Google 自动清理 |
| 安全原因 | Google 检测到异常活动 |

### 如何获取文档 ID？

Google 文档 URL 格式：
```
https://docs.google.com/document/d/DOCUMENT_ID/edit
```

示例：
```
https://docs.google.com/document/d/1aBcD_eFgHiJkLmN_opQr/edit
                        └────────────────────────┘
                              文档 ID
```

### Refresh Token 可以在多台电脑使用吗？

**可以**。Refresh Token 绑定的是 Google 账号，不是设备。你可以在 A 电脑获取，在 B/C/D 电脑使用同一个 Refresh Token。

### 获取 Refresh Token 时出现 "invalid_client" 错误？

请检查：
1. Client ID 和 Client Secret 是否输入正确（不要有多余空格）
2. 是否在 Google Cloud Console 中创建了"桌面应用"类型的 OAuth 凭据
3. 是否已启用 Google Docs API 和 Google Drive API

## 技术栈

- TypeScript
- MCP Protocol
- Google Docs API
- Google Drive API

## 许可证

MIT