AI导哈

Google Drive MCP服务器

一个提供安全Google Drive访问的MCP协议服务器，使用受限的drive.file OAuth范围，仅能访问用户通过Google Picker明确选择的文件或服务器创建的文件。

  • by jfaville
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 jfaville/google-drive-mcp-server

使用说明

Google Drive MCP服务器

A. 模型上下文协议（MCP） 使用限制功能提供安全Google Drive访问的服务器 drive.file OAuth作用域——服务器只能访问它创建的文件或用户通过内置的Google Picker显式选择的文件。它永远无法访问用户驱动器的其余部分。

运作原理

MCP Client (Claude Code, etc.)
        │
        │  JSON-RPC (stdio or HTTP)
        ▼
  Google Drive MCP Server
     ├── /mcp          → MCP protocol endpoint
     ├── /             → Login + Picker web UI
     └── /oauth/callback → OAuth redirect handler
        │
        │  Google Drive API v3 (drive.file scope)
        ▼
    Google Drive
  (permitted files only)

两种运输方式：

  • 标准 --用于将服务器作为子进程启动的本地MCP客户端（例如Claude Desktop）。通过手动OAuth代码流进行身份验证。
  • 超文本传输协议 --公开服务器 http://localhost:PORT/mcp，再加上基于浏览器的登录和选择器UI http://localhost:PORT。这是交互式使用的推荐模式。

先决条件

  • Node.js 18+
  • 启用了Drive API的Google Cloud项目
  • OAuth 2.0凭据（桌面应用程序类型）

谷歌云设置

  1. 首选 Google 云控制台
  2. 创建或选择项目
  3. 启用 Google Drive API 在...之下 API和服务→ 图书馆
  4. 在下创建凭据 API和服务→ 凭证:
    • 点击 创建凭据→ OAuth 2.0客户端ID
    • 应用程序类型： 桌面应用程序
    • 复制 客户端ID 和 客户端密钥
  5. 在...之下 API和服务→ OAuth同意屏幕:
    • 将您的Google帐户电子邮件添加为 测试用户 （应用程序的发布状态为“测试”时需要）

安装

# From archive
tar -xzf google-drive-mcp-server.tar.gz
cd google-drive-mcp-server

# Install dependencies
npm install

# Build
npm run build

配置

复制 .env.example 到 .env 并设置您的凭据：

cp .env.example .env

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

# Transport: 'http' (recommended) or 'stdio'
TRANSPORT=http

# Port for HTTP transport (default: 3000)
PORT=3000

OAuth令牌会自动保存到 .tokens.json 首次登录后。在后续启动时，服务器会重新加载它们-- 您只需要验证一次.

跑步

npm start

HTTP模式（推荐）

打开 http://localhost:3000.

第一轮：

  1. 打开 http://localhost:3000 在浏览器中
  2. 点击 通过 Google 登录 --您将被重定向到谷歌并自动返回
  3. 选择器加载--选择您希望MCP服务器访问的任何文件
  4. 完成。MCP工具现在可以访问这些文件

后续运行： 令牌从以下位置加载 .tokens.json，直接降落在选择器上。

stdio模式

TRANSPORT=stdio npm start

在MCP客户端中：调用 gdrive_authenticate 要获取身份验证URL，请让用户访问它，然后将重定向URL中的代码传递给 gdrive_set_credentials.

开发（热重载）

npm run dev

用途 tsx watch 用于在文件更改时自动重新启动服务器。

这 drive.file 范围和选择器

此服务器使用 https://www.googleapis.com/auth/drive.file --最严格的驱动范围：

可以访问 无法访问
此应用程序创建的文件 用户驱动器中的任何其他文件
通过Google选择器选择的文件 来自其他应用程序的文件

选择器 是授予对现有文件访问权限的机制。当用户通过Picker UI选择文件时，Google的后端注册该OAuth客户端可以访问该文件。后续驱动器API调用该文件成功。

重要实施细节： 选择器需要 setAppId 设置为Google Cloud项目编号（客户端ID的数字前缀）。否则，文件访问权限将无法正确注册。服务器会自动从 GOOGLE_CLIENT_ID.

MCP工具参考

关于人类行为工具的说明： gdrive_authenticate 和 gdrive_open_picker 返回需要人在浏览器中打开的URL。LLM无法点击URL——始终将其转发给用户。

认证

工具 模式 描述
gdrive_authenticate 全部 返回登录说明。在HTTP模式下：指示用户 http://localhost:PORT。在stdio模式下：返回一个Google OAuth URL，并指示用户将代码传递给 gdrive_set_credentials.
gdrive_set_credentials 仅限stdio 用OAuth代码交换令牌。 在HTTP模式下不需要 --浏览器回调会自动处理此问题。

文件访问

工具 说明
gdrive_open_picker 返回选择器URL(http://localhost:PORT).仅限HTTP模式。用户必须打开它并选择文件，然后其他工具才能访问这些文件。

读取操作

工具 说明
gdrive_list_files 列出可访问的文件。支持分页(page_token)，排序(order_by)，并按父文件夹进行筛选。
gdrive_search_files 使用可选的MIME类型和文件夹过滤器按名称搜索可访问的文件。
gdrive_get_file 获取文件的元数据和可选的文本内容。支持谷歌文档（纯文本）、表格（CSV）、幻灯片（纯文本”）和常规文本/JSON文件。

写入操作

工具 说明
gdrive_create_file 创建一个包含可选文本内容的新文件。创建的文件可以在没有选择器的情况下立即访问。
gdrive_create_folder 创建一个新文件夹。
gdrive_update_file 更新文件的名称、文本内容和/或父文件夹。
gdrive_copy_file 复制文件，可以选择重命名或将其放置在其他文件夹中。
gdrive_delete_file 永久删除 一个文件。首先获取名称，以便确认显示已删除的内容。

所有列表/搜索工具支持 response_format: "markdown" （默认，人类可读）或 "json" （结构化、机器可读）。所有工具归还 structuredContent 用于MCP客户端的编程访问。

项目结构

src/
├── index.ts                  # MCP tool registration, Express routes, transport setup
├── constants.ts              # Shared constants (OAuth scopes, limits, MIME type map)
├── types.ts                  # TypeScript interfaces (FileMetadata, FileListResult, etc.)
├── schemas/
│   ├── input-schemas.ts      # Zod input schemas for all tool parameters
│   └── output-schemas.ts     # Zod output schemas for tool structured responses
├── services/
│   ├── drive-service.ts      # OAuth2 client, token persistence, Drive API wrapper
│   └── utils.ts              # Formatting helpers, error handling, query builder
└── tests/
    └── utils.test.ts         # Unit tests for utility functions

已生成/git忽略的文件：

  • dist/ --编译的JavaScript输出
  • .env --凭据和传输配置
  • .tokens.json --保存的OAuth令牌（首次登录后自动创建）

运行测试

npm test

使用Node.js内置测试运行器(node:test).测试涵盖 buildSearchQuery, truncateText，以及 formatError 包括404错误中的查询注入保护和Picker引导等边缘情况。

使用Claude Desktop进行配置

增添 ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-drive": {
      "command": "node",
      "args": ["/absolute/path/to/google-drive-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TRANSPORT": "stdio"
      }
    }
  }
}

安全说明

  • .env 和 .tokens.json 这两个git都被忽略了吗？永远不要提交它们
  • drive.file 是特权最低的驱动器范围；谷歌不需要应用程序验证
  • 服务器仅绑定到 localhost --它不打算暴露在互联网上
  • OAuth令牌包括刷新令牌，并在重新启动时重新加载；删除 .tokens.json 强制重新身份验证
  • 驱动器API搜索查询中的MIME类型和名称值是单引号转义的，以防止查询注入

相关 MCP