https://github.com/amaboh/google-sheets-mcp-server
A Model Context Protocol (MCP) server implementation for Google Sheets
https://github.com/amaboh/google-sheets-mcp-server
Last synced: 2 months ago
JSON representation
A Model Context Protocol (MCP) server implementation for Google Sheets
- Host: GitHub
- URL: https://github.com/amaboh/google-sheets-mcp-server
- Owner: amaboh
- License: mit
- Created: 2025-03-19T10:51:54.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-03-20T00:29:40.000Z (8 months ago)
- Last Synced: 2025-03-20T01:29:51.067Z (8 months ago)
- Language: Python
- Size: 12.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **google-sheets-mcp-server** - A Model Context Protocol (MCP) server implementation for Google Sheets `python` `mcp` `server` `go` `pip install git+https://github.com/amaboh/google-sheets-mcp-server` (🤖 AI/ML)
- awesome-mcp-servers - **google-sheets-mcp-server** - A Model Context Protocol (MCP) server implementation for Google Sheets `python` `mcp` `server` `go` `pip install git+https://github.com/amaboh/google-sheets-mcp-server` (AI/ML)
README
# Google Sheets MCP Server
A Model Context Protocol (MCP) server for Google Sheets that enables Claude Desktop to interact with Google Sheets directly. This server provides tools for creating, reading, writing, and managing Google Sheets through Claude Desktop.
## Features
- Create new Google Sheets
- Read and write data to existing sheets
- Format cells and ranges
- Add and delete sheets
- Write formulas
- Search for sheets
- List available sheets
## Prerequisites
- Python 3.10 or higher
- Google Cloud Project with Google Sheets API enabled
- OAuth 2.0 credentials from Google Cloud Console
- Claude Desktop application
- `uv` package manager (recommended)
## Installation
1. Clone the repository:
```bash
git clone https://github.com/yourusername/google-sheets-mcp-server.git
cd google-sheets-mcp-server
```
2. Create and activate a virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
3. Install dependencies using `uv`:
```bash
uv pip install -e .
```
4. Set up Google Cloud credentials:
- Go to [Google Cloud Console](https://console.cloud.google.com/)
- Create a new project or select an existing one
- Enable the Google Sheets API and Google Drive API
- Create OAuth 2.0 credentials (Desktop app)
- Download the credentials and save as `~/.config/google_sheets_mcp/google-sheets-mcp.json`
## Configuration
1. Configure Claude Desktop:
- Open Claude Desktop settings
- Add the following to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"google_sheets": {
"command": "/path/to/your/.venv/bin/python",
"args": [
"/path/to/your/google_sheets.py",
"--credentials-path",
"/Users/yourusername/.config/google_sheets_mcp/google-sheets-mcp.json",
"--log-level",
"DEBUG"
]
}
}
}
```
2. First-time setup:
- Run the server manually to complete OAuth authentication:
```bash
python google_sheets.py --credentials-path ~/.config/google_sheets_mcp/google-sheets-mcp.json
```
- Follow the browser prompts to authorize the application
- The token will be saved automatically for future use
## Usage
After setup, you can use the following commands in Claude Desktop:
- Create a new sheet: `create_sheet(title: str)`
- Format cells: `format_range(file_id: str, range: str, format: dict)`
- Write formulas: `write_formula(file_id: str, range: str, formula: str)`
- Add sheets: `add_sheet(file_id: str, title: str)`
- Delete sheets: `delete_sheet(file_id: str, sheet_id: int)`
- Get sheet properties: `get_sheet_properties(file_id: str)`
## Development
### Project Structure
```
google-sheets-mcp-server/
├── .venv/ # Virtual environment
├── google_sheets.py # Main server implementation
├── pyproject.toml # Project configuration and dependencies
├── tests/ # Test files
└── README.md # This file
```
### Adding New Features
1. Add new tool methods to the `GoogleSheetsMCP` class
2. Decorate them with `@mcp.tool()`
3. Update the README with new feature documentation
### Running Tests
```bash
pytest
```
## Troubleshooting
1. **Server Connection Issues**
- Check if the server is running
- Verify credentials path in config
- Check logs in Claude Desktop
2. **Authentication Issues**
- Ensure OAuth credentials are valid
- Check if your email is added as a test user
- Try deleting token.json and re-authenticating
3. **API Errors**
- Verify Google Sheets API is enabled
- Check API quotas and limits
- Review error logs for specific issues
## Contributing
1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request
## License
This project is licensed under the MIT License - see the LICENSE file for details.