README.md•7.31 kB
# Google Slides MCP Server
A Model Context Protocol (MCP) server that provides tools for interacting with Google Slides presentations. This server allows you to create new slides and add rectangles to existing slides.
## Features
- **Create New Slides**: Add blank slides to existing Google Slides presentations
- **Add Rectangles**: Insert rectangles with dimensions that are 20% of the slide size
- **OAuth2 Authentication**: Secure authentication flow with Google APIs
- **Presentation Management**: Get presentation info and list slides
## Installation
1. Clone or download this repository
2. Install dependencies:
```bash
npm install
```
3. Build the TypeScript code:
```bash
npm run build
```
## Google Cloud Console Setup
Before using this MCP server, you need to set up a Google Cloud project and enable the Google Slides API:
### 1. Create a Google Cloud Project
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the Google Slides API:
- Go to "APIs & Services" > "Library"
- Search for "Google Slides API"
- Click on it and press "Enable"
### 2. Create OAuth2 Credentials
1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. If prompted, configure the OAuth consent screen first:
- Choose "External" user type
- Fill in the required fields (App name, User support email, etc.)
- Add your email to test users
4. For the OAuth client ID:
- Choose "Desktop application" as the application type
- Give it a name (e.g., "Google Slides MCP Server")
5. Download the credentials JSON file
### 3. Configure Environment Variables
1. Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```
2. Edit `.env` and add your OAuth2 credentials:
```env
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
```
## Usage
### Starting the Server
```bash
npm start
```
Or for development with auto-reload:
```bash
npm run dev
```
### Authentication Flow
Before using the Google Slides tools, you need to authenticate:
1. Call the `get_auth_url` tool to get the OAuth2 authorization URL
2. Visit the URL in your browser and grant permissions
3. Copy the authorization code from the redirect URL
4. Call the `authenticate` tool with the authorization code
The authentication tokens will be saved locally and reused for future requests.
### Available Tools
#### 1. `get_auth_url`
Get the OAuth2 authorization URL for Google Slides access.
**Parameters:** None
**Example:**
```json
{
"name": "get_auth_url",
"arguments": {}
}
```
#### 2. `authenticate`
Complete OAuth2 authentication with authorization code.
**Parameters:**
- `code` (string, required): Authorization code from OAuth2 flow
**Example:**
```json
{
"name": "authenticate",
"arguments": {
"code": "4/0AX4XfWh..."
}
}
```
#### 3. `create_slide`
Create a new slide in a Google Slides presentation.
**Parameters:**
- `presentationId` (string, required): The ID of the Google Slides presentation
- `insertionIndex` (number, optional): Position where to insert the slide (defaults to 0)
**Example:**
```json
{
"name": "create_slide",
"arguments": {
"presentationId": "1BxAB07047kHMdtbgoC48KDz3YMgn9_12345678",
"insertionIndex": 1
}
}
```
#### 4. `add_rectangle`
Add a rectangle to a slide with 20% of slide dimensions.
**Parameters:**
- `presentationId` (string, required): The ID of the Google Slides presentation
- `slideId` (string, required): The ID of the slide to add the rectangle to
- `x` (number, optional): X position of the rectangle (defaults to center)
- `y` (number, optional): Y position of the rectangle (defaults to center)
- `width` (number, optional): Width of the rectangle (defaults to 20% of slide width)
- `height` (number, optional): Height of the rectangle (defaults to 20% of slide height)
**Example:**
```json
{
"name": "add_rectangle",
"arguments": {
"presentationId": "1BxAB07047kHMdtbgoC48KDz3YMgn9_12345678",
"slideId": "slide_12345"
}
}
```
#### 5. `get_presentation_info`
Get information about a Google Slides presentation.
**Parameters:**
- `presentationId` (string, required): The ID of the Google Slides presentation
**Example:**
```json
{
"name": "get_presentation_info",
"arguments": {
"presentationId": "1BxAB07047kHMdtbgoC48KDz3YMgn9_12345678"
}
}
```
#### 6. `list_slides`
List all slides in a Google Slides presentation.
**Parameters:**
- `presentationId` (string, required): The ID of the Google Slides presentation
**Example:**
```json
{
"name": "list_slides",
"arguments": {
"presentationId": "1BxAB07047kHMdtbgoC48KDz3YMgn9_12345678"
}
}
```
## Finding Your Presentation ID
The presentation ID can be found in the Google Slides URL:
```
https://docs.google.com/presentation/d/PRESENTATION_ID_HERE/edit
```
For example, in this URL:
```
https://docs.google.com/presentation/d/1BxAB07047kHMdtbgoC48KDz3YMgn9_abcdefgh/edit
```
The presentation ID is: `1BxAB07047kHMdtbgoC48KDz3YMgn9_abcdefgh`
## Common Workflow
1. **First time setup:**
```bash
# Get authorization URL
{"name": "get_auth_url", "arguments": {}}
# After visiting URL and getting code
{"name": "authenticate", "arguments": {"code": "your_auth_code"}}
```
2. **Create a new slide:**
```bash
{"name": "create_slide", "arguments": {"presentationId": "your_presentation_id"}}
```
3. **Add a rectangle to the slide:**
```bash
{"name": "add_rectangle", "arguments": {"presentationId": "your_presentation_id", "slideId": "returned_slide_id"}}
```
## Error Handling
The server provides detailed error messages for common issues:
- Authentication required
- Invalid presentation ID
- Invalid slide ID
- Network connectivity issues
- Google API quota limits
## Development
### Project Structure
```
src/
├── index.ts # Main MCP server entry point
├── auth.ts # Google OAuth2 authentication
└── slides.ts # Google Slides API service
dist/ # Compiled JavaScript (after npm run build)
package.json # Project dependencies and scripts
tsconfig.json # TypeScript configuration
.env.example # Environment variables template
```
### Scripts
- `npm run build` - Compile TypeScript to JavaScript
- `npm start` - Run the compiled server
- `npm run dev` - Run with ts-node for development
- `npm run watch` - Watch for changes and recompile
## Troubleshooting
### Authentication Issues
- Ensure your Google Cloud project has the Google Slides API enabled
- Check that your OAuth2 credentials are correct in the `.env` file
- Make sure you're using the correct redirect URI
- Verify that your email is added as a test user if using external OAuth consent
### API Errors
- Check that the presentation ID is correct and accessible
- Ensure you have edit permissions for the Google Slides presentation
- Verify that the slide ID exists when adding rectangles
### Permission Errors
The server requires the following Google API scopes:
- `https://www.googleapis.com/auth/presentations` - For creating and editing slides
- `https://www.googleapis.com/auth/drive.file` - For accessing Google Drive files
## License
MIT