Xinotrix-Home/google-sheets-mcp-server

Google Sheets MCP Server

A Model Context Protocol (MCP) server for Google Sheets operations. This server provides comprehensive tools for managing Google Spreadsheets, including creating, reading, updating, and deleting spreadsheets, sheets, and rows.

Features

• 🔧 Spreadsheet Management

  • Create new spreadsheets
  • Find spreadsheets by title
  • Get spreadsheet information

• 📊 Sheet Operations

  • Create new sheets in existing spreadsheets
  • List all sheets in a spreadsheet
  • Delete sheets
  • Get detailed sheet information

• 📝 Row Operations

  • Add rows to sheets (append or insert)
  • Get data from sheets
  • Update specific rows
  • Delete rows

Installation

1. Clone the repository:

git clone <repository-url>
cd google-sheets-mcp-server

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up Google Cloud credentials:

   • Go to Google Cloud Console
   • Create a new project or select an existing one
   • Enable the Google Sheets API and Google Drive API
   • Create credentials (OAuth Client ID or Service Account)
   • Download the credentials JSON file

5. Configure environment variables:

cp .env.example .env
# Edit .env with your configuration

Authentication Methods

Method 1: Service Account (Recommended for servers)

1. Create a service account in Google Cloud Console
2. Download the JSON key file
3. Set the path in .env:

SERVICE_ACCOUNT_PATH=service_account.json

Method 2: OAuth (Recommended for desktop applications)

1. Create OAuth 2.0 Client ID credentials
2. Download the JSON file as credentials.json
3. Set the path in .env:

CREDENTIALS_PATH=credentials.json

Usage

Start the server:

python google_sheets_server.py

Available Tools

Spreadsheet Tools

create_spreadsheet

Create a new Google Spreadsheet.

{
    "title": "My New Spreadsheet"
}

find_spreadsheets

Search for spreadsheets by title.

{
    "title_search": "Budget"  # Optional
}

Sheet Tools

create_sheet

Add a new sheet to an existing spreadsheet.

{
    "spreadsheet_id": "1234567890",
    "title": "New Sheet Name"
}

list_sheets

List all sheets in a spreadsheet.

{
    "spreadsheet_id": "1234567890"
}

delete_sheet

Delete a sheet from a spreadsheet.

{
    "spreadsheet_id": "1234567890",
    "sheet": "Sheet1"
}

get_sheet_info

Get detailed information about a sheet.

{
    "spreadsheet_id": "1234567890",
    "sheet": "Sheet1"
}

Row Tools

add_rows

Add rows to a sheet.

{
    "spreadsheet_id": "1234567890",
    "sheet": "Sheet1",
    "data": [
        ["John", "Doe", 30],
        ["Jane", "Smith", 25]
    ],
    "start_row": 0  # Optional, omit to append
}

get_rows

Get data from a sheet.

{
    "spreadsheet_id": "1234567890",
    "sheet": "Sheet1",
    "range": "A1:C10"  # Optional
}

update_rows

Update specific rows in a sheet.

{
    "spreadsheet_id": "1234567890",
    "sheet": "Sheet1",
    "range": "A1:C2",
    "data": [
        ["UpdatedName", "UpdatedValue"],
        ["Another", "Row"]
    ]
}

delete_rows

Delete rows from a sheet.

{
    "spreadsheet_id": "1234567890",
    "sheet": "Sheet1",
    "start_row": 0,  # 0-indexed
    "end_row": 2     # Exclusive
}

Examples

Python Example

import asyncio
from mcp.client import Client

async def main():
    async with Client() as client:
        # Create a new spreadsheet
        result = await client.call_tool("create_spreadsheet", {
            "title": "My New Budget"
        })
        spreadsheet_id = result['spreadsheetId']
        
        # Add data to the spreadsheet
        await client.call_tool("add_rows", {
            "spreadsheet_id": spreadsheet_id,
            "sheet": "Sheet1",
            "data": [
                ["Category", "Amount"],
                ["Food", 500],
                ["Rent", 1000],
                ["Utilities", 200]
            ]
        })
        
        # Get the data back
        data = await client.call_tool("get_rows", {
            "spreadsheet_id": spreadsheet_id,
            "sheet": "Sheet1"
        })
        print(data)

asyncio.run(main())

Security Considerations

1. Credential Storage: Store credentials securely and never commit them to version control
2. Access Control: Use service accounts with minimal required permissions
3. Environment Variables: Use .env files for configuration (don't commit to git)

Troubleshooting

Common Issues

1. Authentication Error: Ensure credentials file is properly configured
2. Permission Error: Check if the API access is enabled in Google Cloud Console
3. Quota Exceeded: Google Sheets API has rate limits, implement proper error handling

Error Codes

• 404: Spreadsheet or sheet not found
• 403: Permission denied
• 400: Invalid request parameters

Development

To contribute to this project:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License

Support

For support, please open an issue in the GitHub repository.