Google Sheets MCP Server

Model Context Protocol (MCP) server for seamless Google Sheets integration with Claude Desktop and other MCP clients.

✨ Features

• 📖 Read spreadsheet data with A1 notation
• ✍️ Write data to specific cells or ranges
• ➕ Append new rows to spreadsheets
• 📝 Update spreadsheet titles
• ℹ️ Get spreadsheet metadata and information
• 🔐 Secure OAuth 2.0 authentication
• 🚀 Easy setup with environment variables

📦 Installation

NPM (Recommended)

npm install -g @arthur_kim/google-sheets-mcp

Manual Installation

git clone https://github.com/arthur_kim/google-sheets-mcp.git
cd google-sheets-mcp
npm install

🚀 Quick Start

1. Google Cloud Setup

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Google Sheets API
4. Create OAuth 2.0 Client ID (Desktop App)
5. Download credentials

2. Get OAuth Credentials

Set up environment variables with your Google OAuth credentials:

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

3. Configure Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@arthur_kim/google-sheets-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

4. Restart Claude Desktop

Restart Claude Desktop to apply the configuration.

💡 Usage Examples

Once configured, you can interact with Google Sheets naturally in Claude:

Read Spreadsheet

"Read data from spreadsheet 1nOFeUYjxOQClms8dP8Sz8XuGlEocorYi5injSS0MFlY, range Sheet1!A1:D10"

Update Title

"Change the title of spreadsheet 1nOFeUYjxOQClms8dP8Sz8XuGlEocorYi5injSS0MFlY to 'Q1 Sales Report'"

Write Data

"Write 'New Value' to cell A1 in Sheet1"

Append Rows

"Add a new row to Sheet1 with values: ['John', 'Doe', '30', 'Engineer']"

Get Metadata

"Get information about spreadsheet 1nOFeUYjxOQClms8dP8Sz8XuGlEocorYi5injSS0MFlY"

🔧 Available Tools

| Tool | Description | |------|-------------| | sheets_read | Read data from a spreadsheet range | | sheets_write | Write data to specific cells | | sheets_append | Append rows to a spreadsheet | | sheets_update_title | Update spreadsheet title | | sheets_get_info | Get spreadsheet metadata |

📚 Documentation

For detailed setup instructions, see:

• SETUP_GUIDE.md - Complete setup guide
• QUICKSTART.md - Quick start tutorial

🐛 Troubleshooting

Authentication Issues

• Verify OAuth credentials in environment variables
• Ensure Google Sheets API is enabled in Google Cloud Console
• Check that OAuth consent screen is configured

Connection Issues

• Restart Claude Desktop completely
• Check MCP server logs in Claude Desktop
• Verify claude_desktop_config.json syntax

Permission Errors

• Ensure required scope is authorized: https://www.googleapis.com/auth/spreadsheets
• Re-authenticate if permissions were changed

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details

🔗 Links

• Google Sheets API v4
• Model Context Protocol
• OAuth 2.0 Documentation

👨‍💻 Author

arthur_kim