# Google Sheets MCP
A Model Context Protocol (MCP) connector for Google Sheets that allows AI agents to interact with spreadsheets directly.
## Demo
https://github.com/user-attachments/assets/cc4729d9-4e6e-437b-848b-6da9a09418c3
## Setup
1. Clone this repository:
```bash
git clone https://github.com/Jsgordon420365/google-sheets-mcp
cd google-sheets-mcp
```
2. Install dependencies:
`npm install`
3. Build:
`npm run build`
4. Create OAuth credentials in Google Cloud Platform:
- Create a new project in [Google Cloud Console](https://console.cloud.google.com/)
- Enable the [Google Sheets API](https://console.cloud.google.com/marketplace/product/google/sheets.googleapis.com)
- Configure the OAuth consent screen
- Create OAuth client ID credentials (Desktop application) with an appropriate redirect URI (ex: http://localhost:3000/oauth2callback)
- Download the credentials and save as `gcp-oauth.keys.json` in the `dist` subdirectory
5. Start the MCP server (you'll automatically be prompted to authenticate/re-authenticate your Google account when necessary):
`npm run start`
## Usage
Sample config:
```json
{
"mcpServers": {
"google-sheets-mcp": {
"command": "node",
"args": ["/users/gordo/google-sheets-mcp/dist/index.js"]
}
}
}
```
Then you should be able to simply specify your spreadsheetId or ask your agent to create a new one for you.
## Available Actions
| Action | Description |
| --------------------- | ----------------------------------------------------------- |
| `refresh_auth` | Re-authenticate your Google Account when credentials expire |
| `list_sheets` | List all sheets/tabs in a Google Spreadsheet |
| `create_sheet` | Create a new sheet/tab in a Google Spreadsheet |
| `create_spreadsheet` | Create a new Google Spreadsheet |
| `read_all_from_sheet` | Read all data from a specified sheet |
| `read_headings` | Read the column headings from a sheet |
| `read_rows` | Read specific rows from a sheet |
| `read_columns` | Read specific columns from a sheet |
| `edit_cell` | Edit a single cell in a sheet |
| `edit_row` | Edit an entire row in a sheet |
| `edit_column` | Edit an entire column in a sheet |
| `insert_row` | Insert a new row at specified position |
| `insert_column` | Insert a new column at specified position |
| `rename_sheet` | Rename a sheet/tab in a spreadsheet |
| `rename_doc` | Rename a Google Spreadsheet |
| `record_shift_entry` | Record a shift in the Handoff Ledger (Shift_Log) |
| `get_baton_status` | Check who currently has the 'Baton' |
| `call_apps_script` | Trigger custom logic (like Temporal Handshake) via URL |
## Multi-LLM Handoff Protocol (Baton Sync)
This server is optimized for the **Adam, Ben, and Cindy Protocol**, allowing multiple LLMs (Gemini, Claude, ChatGPT) to maintain a synchronized state via a `Shift_Log` tab.
### **The Protocol Rules:**
1. **Check Status**: Before starting any task, run `get_baton_status` to see the latest shift entry and handoff notes.
2. **Identify Yourself**: When recording an entry, use your agent name (e.g., "Gemini", "Claude", "ChatGPT").
3. **Temporal Handshake**: Use `call_apps_script` with the action `temporal_handshake` to sync timestamps if required by the Apps Script logic.
4. **Passing the Baton**: When your shift ends, run `record_shift_entry` with a summary of `actionTaken` and clear `handoffNotes` for the next agent.
### **Apps Script Integration**
- **URL**: `https://script.google.com/macros/s/AKfycbwTx6nUZqmXlH5g_mVCwxPctXe2lR0Y1Hy256TQVOLifAiPu0yJZYvkQywccyxJ38Gs/exec`
- **Action**: `temporal_handshake`
- **Spreadsheet ID**: `1LVcmsIKdgd5uf1K79EtGMgd7epD53x6OBO4cgi7GC9Q`
## License
MIT
