{"id":31581037,"url":"https://github.com/ringo380/claude-google-sheets-mcp","last_synced_at":"2026-05-01T21:34:04.359Z","repository":{"id":316842534,"uuid":"1064868562","full_name":"ringo380/claude-google-sheets-mcp","owner":"ringo380","description":"A comprehensive Model Context Protocol (MCP) server for Google Sheets integration with Claude CLI","archived":false,"fork":false,"pushed_at":"2025-09-27T02:33:24.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T21:55:30.549Z","etag":null,"topics":["ai-tools","automation","claude","claude-cli","google-sheets","mcp","model-context-protocol","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ringo380.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-26T17:18:25.000Z","updated_at":"2025-09-27T02:33:28.000Z","dependencies_parsed_at":"2025-09-27T08:34:38.408Z","dependency_job_id":null,"html_url":"https://github.com/ringo380/claude-google-sheets-mcp","commit_stats":null,"previous_names":["ringo380/claude-google-sheets-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ringo380/claude-google-sheets-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringo380%2Fclaude-google-sheets-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringo380%2Fclaude-google-sheets-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringo380%2Fclaude-google-sheets-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringo380%2Fclaude-google-sheets-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ringo380","download_url":"https://codeload.github.com/ringo380/claude-google-sheets-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringo380%2Fclaude-google-sheets-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32513752,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","automation","claude","claude-cli","google-sheets","mcp","model-context-protocol","python"],"created_at":"2025-10-05T21:52:22.802Z","updated_at":"2026-05-01T21:34:04.332Z","avatar_url":"https://github.com/ringo380.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Google Sheets MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)\n\nA comprehensive Model Context Protocol (MCP) server for Google Sheets integration with Claude. This server provides intuitive access to Google Sheets operations, including spreadsheet discovery, data manipulation, and formatting - specifically optimized for Claude CLI.\n\n**🚀 One-command installation with full Claude CLI automation!**\n\n## ✨ Features\n\n### 🔍 **Spreadsheet Discovery**\n- **List all spreadsheets** in your Google Drive\n- **Advanced search** with filters (name, owner, date, sharing status)\n- **Detailed metadata** about any spreadsheet\n- **Find sheets by name** with partial matching\n\n### 📊 **Data Operations**\n- **Read data** from any range with multiple format options\n- **Write data** to specific ranges with type inference\n- **Append rows** safely without overwriting existing data\n- **Clear ranges** with confirmation safeguards\n\n### 🚀 **Fully Automated Setup**\n- **One-command installation** - Complete Claude CLI integration in minutes\n- **Automatic configuration** - No manual JSON editing required\n- **8 slash commands included** - `/list-sheets`, `/read-sheet`, `/write-sheet`, etc.\n- **Universal authentication** - Works with any Google account type\n- **Smart detection** - Automatically finds and configures Claude CLI\n\n### 🔐 **Universal Authentication**\n- **Works with any Google account type**: Personal, GCP, Google Workspace/GSuite\n- **Interactive setup wizard** for guided authentication configuration\n- **Multiple auth methods**: OAuth 2.0, Service Account, Application Default Credentials\n- **Automatic token refresh** and secure caching\n- **Smart account detection** and permission checking\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.11 or higher\n- Claude CLI installed\n- A Google account (personal, GCP, or Google Workspace/GSuite)\n\n### Installation\n\n#### 🔥 **One-Command Setup (Recommended)**\n\nFor completely automated installation including Claude CLI configuration, slash commands, and authentication setup:\n\n```bash\ngit clone https://github.com/ryanrobson/claude-google-sheets-mcp.git\ncd claude-google-sheets-mcp\n./install-claude-cli.sh\n```\n\nThis script will:\n- ✅ Install all dependencies\n- ⚙️ Automatically configure Claude CLI\n- 📝 Install all 8 slash commands\n- 🔐 Guide you through authentication setup\n- 🧪 Test the installation\n\n#### **Manual Installation**\n\nIf you prefer step-by-step control:\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/ryanrobson/claude-google-sheets-mcp.git\n   cd claude-google-sheets-mcp\n   ```\n\n2. **Install the server**:\n   ```bash\n   ./install.sh\n   ```\n\n3. **Run the interactive setup wizard**:\n   ```bash\n   source venv/bin/activate\n   claude-google-sheets-mcp --setup\n   ```\n\n4. **Add to Claude CLI configuration** (manual):\n   ```json\n   {\n     \"mcpServers\": {\n       \"google-sheets\": {\n         \"command\": \"/path/to/claude-google-sheets-mcp/venv/bin/python\",\n         \"args\": [\n           \"-m\",\n           \"claude_google_sheets.server\"\n         ]\n       }\n     }\n   }\n   ```\n\n5. **Install slash commands** (optional):\n   ```bash\n   ./install-slash-commands.sh\n   ```\n\n## 📖 Usage\n\n### Natural Language Commands\n\nOnce configured, interact with Google Sheets using natural language:\n\n```\nList all my spreadsheets\nRead data from range A1:C10 in my Budget spreadsheet\nWrite this sales data to my Q4 Results sheet\nSearch for spreadsheets containing 'project' in the name\nGet information about my expense tracking sheet\n```\n\n### Slash Commands (Power User)\n\nFor faster access to common operations:\n\n- **`/list-sheets`** - List all your Google Sheets\n- **`/read-sheet`** - Read data from a sheet range\n- **`/write-sheet`** - Write data to a sheet range\n- **`/append-sheet`** - Append new rows to a sheet\n- **`/search-sheets`** - Search sheets with advanced filters\n- **`/sheet-info`** - Get detailed sheet information\n- **`/find-sheet`** - Find sheet by name\n- **`/clear-range`** - Clear data from range (with confirmation)\n\n📚 **See [SLASH_COMMANDS.md](SLASH_COMMANDS.md) for detailed usage guide**\n\n## 🔐 Authentication\n\nThe Google Sheets MCP server supports **all Google account types** and provides an interactive setup wizard to guide you through the authentication process.\n\n### Quick Setup (Recommended)\n\nRun the interactive setup wizard:\n\n```bash\nclaude-google-sheets-mcp --setup\n```\n\nThe wizard will:\n- Detect your account type (Personal, Google Workspace, or GCP)\n- Guide you through the appropriate authentication method\n- Test your configuration to ensure everything works\n- Provide troubleshooting tips if needed\n\n### Authentication Methods\n\n#### 🔐 OAuth 2.0 (Best for personal use)\n- Access your personal Google Sheets\n- Requires one-time Google Cloud project setup\n- Interactive browser-based authentication\n- Automatic token refresh\n\n#### 🤖 Service Account (Best for automation/server use)\n- Non-interactive authentication for scripts\n- Requires sharing sheets with service account email\n- Ideal for team/organization deployments\n\n#### 🌐 Application Default Credentials (Best for GCP users)\n- Uses existing `gcloud` authentication\n- Perfect if you're already using Google Cloud Platform\n- Quick setup with: `gcloud auth application-default login --scopes=\"https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive\"`\n\n### Manual Setup (Advanced)\n\nIf you prefer manual configuration, see the setup wizard prompts for detailed instructions, or place your credentials in `~/.config/google-sheets-mcp/`:\n\n- **OAuth**: `credentials.json` (from Google Cloud Console)\n- **Service Account**: `service-account.json` (service account key)\n- **Application Default**: Use `gcloud auth application-default login`\n\n## 🛠️ Available Tools\n\nThe MCP server exposes these tools:\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `list_spreadsheets` | List all Google Sheets | max_results, query, include_shared |\n| `search_spreadsheets` | Advanced spreadsheet search | name_contains, owner_email, created_after, etc. |\n| `get_spreadsheet_info` | Get detailed metadata | spreadsheet_id |\n| `read_range` | Read data from range | spreadsheet_id, range, value_render_option |\n| `write_range` | Write data to range | spreadsheet_id, range, values, value_input_option |\n| `append_data` | Append rows to sheet | spreadsheet_id, range, values |\n| `clear_range` | Clear data from range | spreadsheet_id, range |\n\n## 🏗️ Architecture\n\n```\nclaude-google-sheets-mcp/\n├── src/claude_google_sheets/\n│   ├── auth/                 # Authentication management\n│   ├── tools/               # MCP tool implementations\n│   ├── core/                # Base classes and utilities\n│   └── server.py            # Main MCP server\n├── slash-commands/          # Claude CLI slash commands\n├── tests/                   # Test suite\n└── docs/                    # Documentation\n```\n\n## 🧪 Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/ryanrobson/claude-google-sheets-mcp.git\ncd claude-google-sheets-mcp\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n### Run Tests\n\n```bash\npython test_server.py\n```\n\n### Code Quality\n\n```bash\nblack src/\nisort src/\nflake8 src/\nmypy src/\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Quick Contribution Guide\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite: `python test_server.py`\n6. Commit your changes: `git commit -m 'Add amazing feature'`\n7. Push to the branch: `git push origin feature/amazing-feature`\n8. Open a Pull Request\n\n## 📋 Roadmap\n\n- [ ] **Formatting tools** - Cell formatting, colors, borders\n- [ ] **Chart creation** - Generate charts from data\n- [ ] **Batch operations** - Multiple operations in single request\n- [ ] **Sheet management** - Create, delete, rename sheets\n- [ ] **Collaboration features** - Comments, suggestions\n- [ ] **Advanced formulas** - Formula manipulation and analysis\n- [ ] **Export/Import** - CSV, Excel, PDF export\n- [ ] **Webhook support** - Real-time change notifications\n\n## 🔒 Security \u0026 Privacy\n\n- **No data storage**: This server doesn't store your spreadsheet data\n- **Credential security**: Uses Google's official authentication libraries\n- **Minimal permissions**: Requests only necessary API scopes\n- **Local processing**: All operations performed locally\n- **Audit trail**: All API calls logged for debugging\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 📊 Comparison with Other Solutions\n\n| Feature | This MCP Server | Google Sheets API | Other MCP Servers |\n|---------|----------------|-------------------|-------------------|\n| Spreadsheet Discovery | ✅ Full Drive integration | ❌ Requires sheet IDs | ❌ Limited or none |\n| Claude CLI Optimized | ✅ Purpose-built | ❌ Generic API | ⚠️ Basic integration |\n| Slash Commands | ✅ 8 commands included | ❌ None | ❌ None |\n| Authentication Options | ✅ Multiple methods | ✅ Standard OAuth | ⚠️ Varies |\n| Error Handling | ✅ User-friendly | ❌ Technical errors | ⚠️ Varies |\n| Interactive Workflows | ✅ Guided prompts | ❌ None | ❌ None |\n\n## 🆘 Troubleshooting\n\n### Common Issues\n\n**\"Authentication failed\"**\n- Run the setup wizard: `claude-google-sheets-mcp --setup`\n- For GCP users: Use `gcloud auth application-default login` with proper scopes\n- Check that Google Sheets and Drive APIs are enabled in your Google Cloud project\n\n**\"Spreadsheet not found\"**\n- Use `/list-sheets` to see available spreadsheets\n- Check spreadsheet sharing permissions (especially for service accounts)\n- Verify the spreadsheet ID is correct\n\n**\"Invalid range\"**\n- Use A1 notation (e.g., \"A1:C10\", \"Sheet1!A1:C10\")\n- Check that the range exists in the spreadsheet\n- Include sheet name if the spreadsheet has multiple tabs\n\n**\"Insufficient permissions\"**\n- For Application Default Credentials, ensure you have the right scopes:\n  ```bash\n  gcloud auth application-default login --scopes=\"https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive\"\n  ```\n- For service accounts, ensure the service account email has been granted access to your spreadsheets\n\n### Getting Help\n\n1. Check the [Issues](https://github.com/ryanrobson/claude-google-sheets-mcp/issues) page\n2. Review [SLASH_COMMANDS.md](SLASH_COMMANDS.md) for usage examples\n3. Enable debug logging: `--debug` flag\n4. Join discussions in the repository\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **Anthropic** for Claude and the Model Context Protocol\n- **Google** for the Sheets and Drive APIs\n- **MCP Community** for tools and inspiration\n- **Contributors** who help improve this project\n\n## 📞 Support\n\n- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/ryanrobson/claude-google-sheets-mcp/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/ryanrobson/claude-google-sheets-mcp/discussions)\n- 📖 **Documentation**: [Wiki](https://github.com/ryanrobson/claude-google-sheets-mcp/wiki)\n\n---\n\n**Made with ❤️ for the Claude and MCP community**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringo380%2Fclaude-google-sheets-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fringo380%2Fclaude-google-sheets-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringo380%2Fclaude-google-sheets-mcp/lists"}