google-mcp-server/README.md

Google Suite MCP Server for Cursor and other MCP clients

# Google MCP Server

A comprehensive MCP (Model Context Protocol) server that provides access to Google services including Chat, Sheets, Drive, and Calendar. This package can be easily installed and used with `npx` for seamless integration with Cursor and other MCP clients.

## Features

- **Google Chat**: Send messages, manage spaces, search conversations
- **Google Sheets**: Create, read, write, and manage spreadsheets
- **Google Drive**: File management, sharing, and organization
- **Google Calendar**: Event management, scheduling, and availability
- **Unified Authentication**: Single setup for all Google services
- **Easy Installation**: One-command installation via npm

## Prerequisites

- **Python 3.7+**: Required for the MCP server
- **Node.js 14+**: Required for npm/npx functionality
- **Google Cloud Project**: With APIs enabled for the services you want to use

## Quick Start

### 1. Install and Setup

```bash
# Run setup (first time only)
npx google-mcp-server --setup
```

This will:
- Download credentials from Google Cloud Console
- Authenticate with Google services
- Create necessary token files

### 2. Start the Server

```bash
# Start the MCP server
npx google-mcp-server
```

The server will start and be available for Cursor to connect.

## Detailed Setup

### 1. Google Cloud Console Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the following APIs:
   - Google Chat API
   - Google Sheets API
   - Google Drive API
   - Google Calendar API
4. Create credentials:
   - Go to "APIs & Services" > "Credentials"
   - Click "Create Credentials" > "OAuth 2.0 Client IDs"
   - Choose "Desktop application"
   - Download the JSON file and rename it to `credentials.json`
   - Place it in your project directory

### 2. Authentication

Run the setup command:

```bash
npx google-mcp-server --setup
```

This will:
- Open your browser for Google authentication
- Request necessary permissions
- Save authentication tokens

### 3. Configure Cursor

In Cursor, add the MCP server to your configuration:

```json
{
  "mcpServers": {
    "google-mcp": {
      "command": "npx",
      "args": ["google-mcp-server"]
    }
  }
}
```

## Usage

### Starting the Server

```bash
# Basic start
npx google-mcp-server

# With setup (if needed)
npx google-mcp-server --setup

# Help
npx google-mcp-server --help
```

### Available Tools

The server provides tools for:

#### Google Chat
- Send messages to spaces
- List and manage spaces
- Search conversations
- Manage users and participants

#### Google Sheets
- Create new spreadsheets
- Read and write data
- Format cells
- Manage ranges

#### Google Drive
- List and search files
- Upload and download files
- Share files with others
- Create folders

#### Google Calendar
- List and manage calendars
- Create and update events
- Check availability
- Search events

## Configuration

### Environment Variables

- `GOOGLE_CREDENTIALS_PATH`: Path to credentials.json (default: ./credentials.json)
- `GOOGLE_TOKEN_PATH`: Path to token file (default: ./google_shared_token.json)

### Provider Configuration

The server uses `provider-config.yaml` for configuration. You can customize:

- Token paths
- API endpoints
- Authentication settings

## Troubleshooting

### Common Issues

1. **Python not found**
   - Ensure Python 3.7+ is installed and in PATH
   - Try: `python --version` or `python3 --version`

2. **Missing credentials**
   - Run: `npx google-mcp-server --setup`
   - Ensure `credentials.json` is in the project directory

3. **Authentication errors**
   - Delete `google_shared_token.json` and run setup again
   - Check that APIs are enabled in Google Cloud Console

4. **Import errors**
   - Install dependencies: `pip install -r requirements.txt`
   - Check Python version compatibility

### Debug Mode

For detailed logging, set the environment variable:

```bash
export PYTHONPATH=./src
npx google-mcp-server
```

## Development

### Local Development

```bash
# Clone the repository
git clone https://github.com/yourusername/google-mcp-server.git
cd google-mcp-server

# Install dependencies
pip install -r requirements.txt

# Run setup
python setup_unified_auth.py

# Start server
python start_mcp_server.py
```

### Building the Package

```bash
# Install dependencies
npm install

# Build package
npm run build

# Publish to npm
npm publish
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/google-mcp-server/issues)
- **Documentation**: [Project Wiki](https://github.com/yourusername/google-mcp-server/wiki)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/google-mcp-server/discussions)

## Changelog

### v1.0.0
- Initial release
- Google Chat, Sheets, Drive, and Calendar support
- Unified authentication
- npm package support