Google Docs & Drive MCP Server

# Google Cloud Setup for GoogleDocsMCP ## Overview This MCP server requires Google Cloud Project credentials with Google Docs API enabled. This guide will walk you through setting up OAuth 2.0 authentication for the AgenticLedger platform. ## Prerequisites - Google Account - Access to Google Cloud Console - Permission to create/modify Google Cloud Projects - Node.js 18+ installed ## Step 1: Create Google Cloud Project 1. Go to [Google Cloud Console](https://console.cloud.google.com) 2. Click "Select a project" → "New Project" 3. Name: `AgenticLedger-Docs-MCP` 4. Click "CREATE" ## Step 2: Enable Required APIs 1. Navigate to "APIs & Services" → "Library" 2. Search and enable the following APIs: - **Google Docs API** (Required) - **Google Drive API** (Required for file operations and comments) ## Step 3: Configure OAuth Consent Screen 1. Go to "APIs & Services" → "OAuth consent screen" 2. Choose User Type: **External** 3. Click "CREATE" 4. Fill in App Information: - **App name**: `AgenticLedger Docs MCP` - **User support email**: Your email address - **Developer contact information**: Your email address 5. Click "SAVE AND CONTINUE" ### Add Scopes 6. Click "ADD OR REMOVE SCOPES" 7. Add the following scopes: - `https://www.googleapis.com/auth/documents` (Read/write docs) - `https://www.googleapis.com/auth/drive.file` (Access specific files) - `https://www.googleapis.com/auth/drive` (Full Drive access - for comments, file management) 8. Click "UPDATE" 9. Click "SAVE AND CONTINUE" ### Add Test Users 10. Click "ADD USERS" 11. Enter your Google email address 12. Click "ADD" 13. Click "SAVE AND CONTINUE" 14. Review summary and click "BACK TO DASHBOARD" ## Step 4: Create OAuth 2.0 Credentials 1. Go to "APIs & Services" → "Credentials" 2. Click "CREATE CREDENTIALS" → "OAuth client ID" 3. Application type: **Desktop app** 4. Name: `AgenticLedger Docs Desktop Client` 5. Click "CREATE" ## Step 5: Download Credentials 1. Click the "DOWNLOAD JSON" button in the popup 2. Save the file as `credentials.json` in the MCP server directory 3. **IMPORTANT**: Rename to exactly `credentials.json` **Security Warning**: This file contains sensitive credentials. Never commit to version control! ## Step 6: First-Time Authorization 1. Build the server (if not already done): ```bash npm run build ``` 2. Run the server for first-time authorization: ```bash node ./dist/server.js ``` 3. The terminal will display: - "Attempting to authorize..." - "Authorize this app by visiting this url:" - A long `https://accounts.google.com/...` URL 4. Copy the entire URL and paste into your browser 5. Log in with the **same Google account** you added as Test User 6. Review permissions and click "Allow" 7. Your browser will redirect to `http://localhost/?code=...` and show "This site can't be reached" - **THIS IS NORMAL** 8. Copy the authorization code from the URL: - Look for `code=4/0Axxx...` in the address bar - Copy everything between `code=` and `&scope` 9. Paste the code into the terminal prompt: ``` Enter the code from that page here: [paste code here] ``` 10. Press Enter 11. Success indicators: ``` Authentication successful! Token stored to .../token.json MCP Server running... ``` 12. A `token.json` file will be created in the server directory **Security Warning**: `token.json` contains access tokens. Never commit to version control! ## Environment Variables The server uses file-based authentication. Ensure these files exist: - `credentials.json` - OAuth 2.0 client credentials - `token.json` - Access/refresh tokens (created after first auth) ## Verification Test the server with: ```bash node dist/server.js ``` Should start without errors and display: ``` Attempting to authorize Google API client... Google API client authorized successfully. MCP Server running... ``` ## Troubleshooting ### "Authentication failed" - Verify `credentials.json` exists and is valid - Ensure APIs are enabled (Docs + Drive) - Check Test User is added on OAuth Consent Screen - Delete `token.json` and re-authorize ### "Token has been expired or revoked" - Delete `token.json` - Run `node ./dist/server.js` to re-authorize - Follow authorization steps again ### "Permission denied" - Ensure user account has access to the document - Check document sharing settings - Verify OAuth scopes include necessary permissions ### "This site can't be reached" after clicking Allow - **This is expected behavior** - Just copy the code from the URL as instructed above ### "Invalid grant" error - Your authorization code may have expired (they're single-use) - Restart the authorization process - Complete it faster (codes expire quickly) ## File Structure ``` GoogleDocsMCP/ ├── credentials.json # OAuth 2.0 client credentials (create this) ├── token.json # Access tokens (auto-generated) ├── dist/ │ └── server.js # Compiled server └── src/ └── auth.js # Authentication logic ``` ## Security Best Practices 1. **Never commit credentials**: ```gitignore credentials.json token.json ``` 2. **Token expiration**: Access tokens expire after 1 hour, but refresh tokens allow automatic renewal 3. **Revoke access**: Go to https://myaccount.google.com/permissions to revoke access 4. **Separate credentials**: Use different OAuth clients for dev/staging/prod 5. **Monitor usage**: Check Cloud Console → "APIs & Services" → "Dashboard" ## OAuth vs Service Account **This server uses OAuth 2.0** (not Service Accounts) because: - Better for user-specific data access - More appropriate for desktop applications - Allows accessing user's own documents without sharing **Service Accounts** are better for: - Server-to-server communication - Accessing shared organizational resources - Automated background processes ## Rate Limits Google Docs API quotas: - **Read requests**: 300 per minute per user - **Write requests**: 300 per minute per user - **Per-project quota**: 25,000 requests per day Monitor usage in Cloud Console to stay within limits. ## Cost Considerations - Google Docs API is **FREE** for most use cases - Cloud Project is free (no compute resources) - OAuth credentials are free All operations are free within quota limits. ## Re-Authorization To re-authorize (e.g., after revoking access or changing scopes): 1. Delete `token.json` 2. Run `node ./dist/server.js` 3. Complete authorization flow again 4. New `token.json` will be created ## Scope Management Current scopes in `src/auth.ts`: ```javascript const SCOPES = [ 'https://www.googleapis.com/auth/documents', 'https://www.googleapis.com/auth/drive.file', 'https://www.googleapis.com/auth/drive' ]; ``` If you modify scopes: 1. Delete `token.json` 2. Update OAuth Consent Screen scopes in Cloud Console 3. Re-authorize as described above