@lmdat/google-sheets-oauth-mcp
A local MCP server that lets you manage Google Sheets via OAuth (acting as the logged-in Google user), eliminating the need to manually share files like with a Service Account.
Find Spreadsheets (
drive_list_spreadsheets): Search for Google Sheets in your Drive by name; returns file name, ID, URL, modified time, and owner.Create a New Spreadsheet (
sheets_create): Create a new Google Sheet with a custom title, optionally place it in a specific Drive folder, and pre-create multiple named tabs.Read Sheet Data (
sheets_read): Read values from a specific range (A1 notation), returning a 2D array of rows and columns.Write/Overwrite Data (
sheets_write): Write data into a specific range, with support for raw or user-entered value parsing (formulas, dates, etc.).Append Rows (
sheets_append): Append new rows to the end of an existing data table without overwriting existing data.Clear a Range (
sheets_clear): Clear values from a range while preserving formatting and borders.List Tabs (
sheets_list_tabs): List all tabs and their IDs within a spreadsheet.Create Standard Charts (
sheets_create_chart): Create COLUMN, BAR, LINE, AREA, SCATTER, or PIE charts from existing data, with support for stacked charts and custom placement.Create Candlestick Charts (
sheets_create_candlestick_chart): Create OHLC candlestick charts using a 5-column Date-Open-High-Low-Close range.Write JSON Data (
sheets_write_json): Write JSON data directly into a Google Sheet.Append JSON Data (
sheets_append_json): Append JSON data to a Google Sheet, creating the file or tab if it doesn't exist yet.
Provides tools for reading, writing, creating Google Sheets, including chart creation and spreadsheet management, using OAuth authentication. Also supports listing spreadsheets via the Google Drive API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@lmdat/google-sheets-oauth-mcp Create a new sheet named 'Expenses' with columns for date, category, amount."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@lmdat/google-sheets-oauth-mcp
Local MCP server (Node.js + TypeScript) đọc/ghi/tạo Google Sheets, kèm tạo chart, thông qua OAuth — server hoạt động đại diện chính tài khoản Google đang đăng nhập, không cần share thủ công từng file như cách dùng Service Account.
Yêu cầu
Node.js 18+
Tài khoản Google (cá nhân hoặc Workspace)
1 project trên Google Cloud Console
Related MCP server: google-workspace-mcp-server
1. Setup Google Cloud Console
Vào console.cloud.google.com, tạo hoặc chọn 1 project.
APIs & Services → Library → enable Google Sheets API và Google Drive API.
APIs & Services → OAuth consent screen:
User type: chọn External (tài khoản Gmail cá nhân chỉ có lựa chọn này; Internal chỉ dành cho tài khoản Google Workspace).
Điền App name và support email (giá trị tùy ý, không ảnh hưởng chức năng).
Sau khi tạo, vào tab Audience → bấm Publish App → Confirm. Bước này nên làm ngay từ đầu — nếu bỏ qua, app ở trạng thái Testing và refresh token sẽ tự hết hạn sau 7 ngày.
APIs & Services → Credentials → Create Credentials → OAuth client ID:
Application type: Desktop app (không chọn Web application).
Lưu lại
Client IDvàClient secrethiện ra sau khi tạo.
2. Cài đặt
npm install3. Build
Lệnh | Output | Dùng khi nào |
|
| Phát triển/debug, code dễ đọc |
|
| Dùng để chạy thật / publish |
|
| Muốn code khó đọc hơn khi chia sẻ (không phải mã hóa, chỉ gây khó đọc) |
Build tối thiểu 1 lần trước khi cấu hình opencode ở bước tiếp theo.
4. Cấu hình credential
export GOOGLE_OAUTH_CLIENT_ID="xxx.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="GOCSPX-xxx"Hoặc khai báo trực tiếp trong config opencode ở bước 5 (mục environment), không cần export
ra shell.
Biến môi trường optional:
Var | Default | Khi nào cần đổi |
|
| Port bị chương trình khác chiếm dụng |
|
| Muốn lưu file token ở vị trí khác |
5. Cấu hình trong opencode
Có 2 cách trỏ tới MCP server, chọn 1 trong 2.
Cách 1 — Trỏ trực tiếp đến file (đơn giản, không cần publish)
"google-sheets": {
"type": "local",
"command": [
"node",
"/duong-dan-tuyet-doi/google-sheets-oauth-mcp/dist/index.js"
],
"enabled": true,
"environment": {
"GOOGLE_OAUTH_CLIENT_ID": "xxx.apps.googleusercontent.com",
"GOOGLE_OAUTH_CLIENT_SECRET": "GOCSPX-xxx"
}
}Thay /duong-dan-tuyet-doi/... bằng đường dẫn thật trên máy đang chạy opencode. Phù hợp khi
chỉ dùng trên 1 máy, không cần chia sẻ cho người khác.
Cách 2 — Dùng qua npm package (cần publish trước)
Nếu package đã được publish lên npm registry (xem mục 8), cấu hình gọn hơn, không cần biết đường dẫn cụ thể trên máy:
"google-sheets": {
"type": "local",
"command": [
"npx",
"-y",
"@lmdat/google-sheets-oauth-mcp@latest"
],
"enabled": true,
"environment": {
"GOOGLE_OAUTH_CLIENT_ID": "xxx.apps.googleusercontent.com",
"GOOGLE_OAUTH_CLIENT_SECRET": "GOCSPX-xxx"
}
}6. Lần đầu sử dụng — cần đăng nhập 1 lần
Khi opencode gọi tool đầu tiên (ví dụ drive_list_spreadsheets), server sẽ:
Tự mở browser (hoặc in URL ra log nếu máy không tự mở được trình duyệt — copy URL đó dán vào browser thủ công).
Đăng nhập Google và bấm Allow.
Browser hiện thông báo đăng nhập thành công → token được lưu vào
~/.mcp-google-sheets/token.json.
Từ lần sau không cần đăng nhập lại — token tự refresh ngầm.
Flow này cần trình duyệt trên cùng máy đang chạy MCP server, vì server mở 1 HTTP server tạm trên
127.0.0.1để nhận redirect từ Google. Nếu server được chạy trên môi trường không có giao diện (ví dụ VPS headless), flow này sẽ không hoạt động và cần cách xác thực khác.
7. Đổi scope sau này → phải đăng nhập lại
Nếu chỉnh sửa danh sách scope trong src/auth.ts, cần xóa file token cũ
(~/.mcp-google-sheets/token.json) rồi chạy lại để đăng nhập lại. Google gắn cố định scope vào
thời điểm cấp quyền — token cũ không tự nhận thêm quyền mới.
8. (Tùy chọn) Publish lên npm để dùng theo Cách 2
npm login # nếu chưa đăng nhập npm
npm run build:min
npm publish --access public # bắt buộc thêm flag này nếu dùng scoped package (@username/...)Kiểm tra trước khi publish thật:
npm run build:min && npm pack --dry-run9. Danh sách tool
Tool | Chức năng |
| Tìm sheet theo tên (Drive API), không cần biết ID trước |
| Tạo sheet mới, tùy chọn đặt vào folder cụ thể và tạo sẵn nhiều tab |
| Đọc 1 range, trả về mảng 2 chiều |
| Ghi đè giá trị trong 1 range |
| Thêm hàng vào cuối bảng dữ liệu hiện có |
| Xóa giá trị trong 1 range (giữ nguyên format) |
| Liệt kê tên các tab trong file |
| Tạo chart COLUMN/BAR/LINE/AREA/SCATTER/PIE từ dữ liệu có sẵn |
| Tạo chart nến (OHLC) cho dữ liệu giá |
| Ghi dữ liệu JSON vào Google Sheet |
| Tự động append dữ liệu JSON vào Google Sheet (tự tạo file/tab nếu chưa có) |
Mọi tool đọc/ghi (trừ drive_list_spreadsheets và sheets_create) đều cần spreadsheet_id —
lấy từ URL của sheet hoặc dùng drive_list_spreadsheets để tìm theo tên.
Lưu ý khi dùng 2 tool tạo chart
Mọi range truyền vào phải ghi đủ tên sheet, theo dạng
"TenSheet!A2:E50". Range thiếu tên sheet không được hỗ trợ.sheets_create_candlestick_chartyêu cầudata_rangecó đúng 5 cột liên tiếp, theo thứ tự cố định: Date, Open, High, Low, Close — đúng convention chuẩn của Google Sheets khi chọn data bằng tay qua Insert > Chart. Sai thứ tự cột (ví dụ đảo Open/Close) không gây ra lỗi — chart vẫn được tạo nhưng màu nến hiển thị ngược nghĩa, cần tự kiểm tra bằng mắt sau khi tạo.anchor_cell(vị trí đặt chart) là optional ở cả 2 tool — nếu không truyền, chart tự đặt ngay bên phải vùng dữ liệu nguồn.
10. Scope OAuth đang sử dụng
const SCOPES = [
"https://www.googleapis.com/auth/spreadsheets", // đọc/ghi/tạo sheet
"https://www.googleapis.com/auth/drive.readonly", // tìm/list toàn bộ sheet user có quyền
"https://www.googleapis.com/auth/drive.file", // move file mới tạo vào folder
];drive.file chỉ cho phép truy cập file do chính app này tạo ra (hoặc do user chọn qua
Picker) — không đủ để di chuyển hay sửa file cũ không phải do app tạo. Vì vậy cần thêm
drive.readonly riêng cho việc tìm/list sheet có sẵn. Scope drive (toàn quyền) không được
sử dụng vì rộng hơn mức cần thiết.
11. Ví dụ câu lệnh trong opencode
Tìm sheet có chữ "Ngân sách"
Tạo sheet mới tên "Theo dõi cổ phiếu 2026" với 2 tab: Giao dịch, Tổng hợp
Đọc A1:E20 trong tab Giao dịch của sheet [tên/id vừa tạo]
Append 1 hàng vào tab Giao dịch: 2026-06-25, VNM, Buy, 1000, 42500
Tạo candlestick chart "Giá VNM Q2 2026" từ range Data!A2:E5012. So sánh với bản dùng Service Account
Service Account | OAuth (bản này) | |
Truy cập sheet có sẵn | Phải share thủ công email service account | Tự thấy mọi sheet user đã có quyền |
Tìm sheet theo tên | Không hỗ trợ | Có, qua |
File mới tạo | Thuộc Drive của service account | Thuộc Drive của chính user |
Setup ban đầu | Nhanh, không cần đăng nhập trình duyệt | Cần đăng nhập trình duyệt 1 lần, cấu hình OAuth consent screen |
Phù hợp | Vài sheet cố định, biết trước ID | Cần linh hoạt nhiều sheet, tạo/tìm theo tên |
Available Tools
9 toolsdrive_list_spreadsheetsTìm Google Sheet theo tênB
List các Google Sheet trong Drive của chính user đang login (không cần share thủ công, vì OAuth đại diện chính user đó). Dùng để tìm spreadsheet_id theo tên thay vì copy URL. Trả về JSON array, mỗi item: {name, id, url, modifiedTime, owner}.
Inputs: max_results, name_contains.
sheets_appendAppend hàng mới vào Google SheetA
Thêm hàng mới vào cuối bảng dữ liệu hiện có (không đè dữ liệu cũ).
Inputs: range (required), values (required), spreadsheet_id (required), value_input_option.
sheets_clearXóa giá trị trong 1 rangeA
Xóa nội dung (giá trị) trong 1 range, không xóa format/border.
Inputs: range (required), spreadsheet_id (required).
sheets_createTạo Google Sheet mớiA
Tạo 1 spreadsheet mới (rỗng). Mặc định nằm ở root My Drive của account đang login. Truyền folder_id nếu muốn đặt luôn vào 1 folder cụ thể.
Inputs: title (required), folder_id, sheet_titles.
sheets_create_candlestick_chartTạo candlestick chart (nến) trong Google SheetA
Tạo chart nến cho dữ liệu giá (OHLC). data_range PHẢI có ĐÚNG 5 cột liên tiếp theo thứ tự cố định: Date, Open, High, Low, Close — đúng convention chuẩn của Google Sheets (giống khi tự chọn data trên Insert > Chart bằng tay). Ví dụ: "Data!A2:E50" (không gồm dòng header).
Inputs: title (required), data_range (required), spreadsheet_id (required), anchor_cell.
sheets_create_chartTạo chart cơ bản trong Google SheetA
Tạo 1 chart COLUMN/BAR/LINE/AREA/SCATTER/PIE từ data có sẵn, chart được embed thẳng vào tab. Mọi range PHẢI ghi đủ tên sheet, dạng "TenSheet!A2:A10" — không hỗ trợ range thiếu tên sheet.
Inputs: title (required), chart_type (required), domain_range (required), series_ranges (required), +3 more.
sheets_list_tabsList các tab/sheet trong fileA
Liệt kê tên + ID các tab (sheet con) trong 1 Google Sheet file.
Inputs: spreadsheet_id (required).
sheets_readĐọc dữ liệu từ Google SheetA
Đọc giá trị 1 vùng (range) trong Google Sheet, trả về dạng mảng 2 chiều (hàng x cột).
Inputs: range (required), spreadsheet_id (required).
sheets_writeGhi đè dữ liệu vào Google SheetA
Ghi đè giá trị vào 1 range cụ thể. Dữ liệu cũ trong range sẽ bị thay thế hoàn toàn.
Inputs: range (required), values (required), spreadsheet_id (required), value_input_option.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose: listing, appending, clearing, creating, charting, reading, writing, and managing tabs. No two tools overlap in functionality.
Most tools follow the 'sheets_<action>' pattern consistently. The only deviation is 'drive_list_spreadsheets' with a different prefix, which is acceptable given the different domain (Drive vs Sheets).
With 9 tools, the server covers essential Google Sheets operations without being overwhelming. Each tool serves a distinct and necessary function.
The tool set covers core CRUD operations (create, read, write, clear) and includes chart creation and tab management. Minor gaps like lacking a delete spreadsheet tool are acceptable for the scope.
Maintenance
Related MCP Connectors
Streamable HTTP MCP server for Google Calendar and Sheets with OAuth login.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Hosted Google Business Profile MCP server: reviews, posts, profile edits, Maps rank. OAuth sign-in.
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP Server for Google Services, with the ability to define your own scopes and bring your own oauth key.3MIT
- AlicenseAqualityDmaintenanceMCP server for Google Workspace APIs - Docs, Sheets, Drive, Gmail, and Calendar. Enables reading, creating, and editing Google Docs and Sheets, managing comments, reading emails, and viewing calendar events.3417MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Google Docs and Sheets that enables AI assistants to read, create, edit, style, export, and collaborate on documents using local OAuth authentication.26 npm1MIT
- AlicenseNot gradedqualityCmaintenanceMCP server to read, write, create, and format Google Sheets via OAuth2 authentication, providing tools for spreadsheet management.550 npmMIT