Google Appscript MCP Server

🚀 Google Apps Script MCP Server

This Google Apps Script MCP (Model Context Protocol) Server offers seamless integration with the Google Apps Script API. It enables you to manage script projects, deployments, versions, and executions via any MCP-compatible client, such as Claude Desktop, VS Code with Cline, or Postman.

🚀 Quick Start

Prerequisites

Before starting, ensure you have:

• Node.js (v18+ required, v20+ recommended) - Download here
• npm (included with Node.js)
• Google Account with access to Google Cloud Console
• Git (for cloning the repository)

Steps

1. Clone the Repository

   git clone https://github.com/mohalmah/google-apps-script-mcp-server.git
   cd google-apps-script-mcp-server
   

2. Install Dependencies

   npm install
   

3. Set Up Google Cloud OAuth: Follow the detailed OAuth setup guide below.
4. Run OAuth Setup

   npm run setup-oauth
   

5. Test the Server

   npm start
   

✨ Features

Core Capabilities

• Project Management: Create, retrieve, and update Google Apps Script projects
• Deployment Management: Create, list, update, and delete script deployments
• Version Control: Create and manage script versions
• Content Management: Get and update script content and files
• Process Monitoring: List and monitor script execution processes
• Metrics Access: Retrieve script execution metrics and analytics
• Script Execution: Run Google Apps Script functions remotely

Other Features

• ✅ OAuth 2.0 Authentication - Secure token management with automatic refresh
• ✅ 16 Comprehensive Tools - Complete Google Apps Script API coverage
• ✅ MCP Protocol Compliance - Works with Claude Desktop, VS Code, and other MCP clients
• ✅ Secure Token Storage - OS-specific secure storage for refresh tokens
• ✅ Auto Token Refresh - Handles token expiration automatically
• ✅ Detailed Logging - Comprehensive error handling and debugging

📦 Installation

Clone the Repository

git clone https://github.com/mohalmah/google-apps-script-mcp-server.git
cd google-apps-script-mcp-server

Install Dependencies

npm install

Google Cloud Console Setup

1. Create or Select a Google Cloud Project

1. Go to Google Cloud Console
2. Click the project dropdown at the top
3. Click "New Project" or select an existing project
4. If creating new:
   • Enter a project name (e.g., "Google Apps Script MCP")
   • Note your Project ID (you'll need this)
   • Click "Create"

2. Enable Required APIs

1. In the Google Cloud Console, navigate to APIs & Services → Library
2. Search for and enable the following APIs:
   • Google Apps Script API (required)
   • Google Drive API (recommended for file access)
   • Google Cloud Resource Manager API (for project operations)

3. Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Choose External (unless you're in a Google Workspace organization)
3. Fill in the required information:
   • App name: "Google Apps Script MCP Server"
   • User support email: Your email address
   • App logo: (optional)
   • App domain: Leave blank for development
   • Developer contact information: Your email address
4. Click "Save and Continue"

4. Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials
2. Click "+ CREATE CREDENTIALS" → "OAuth 2.0 Client IDs"
3. For Application Type, select "Web application"
4. Configure the client:
   • Name: "Google Apps Script MCP Client"
   • Authorized JavaScript origins: (leave empty for now)
   • Authorized redirect URIs: Add exactly this URL:

     http://localhost:3001/oauth/callback
     

5. Click "Create"
6. IMPORTANT: Copy your Client ID and Client Secret immediately

Configure Environment Variables

1. Create .env File

# On Windows
type nul > .env

# On macOS/Linux
touch .env

2. Add OAuth Credentials

# Google Apps Script API OAuth Configuration
GOOGLE_APP_SCRIPT_API_CLIENT_ID=your_client_id_here
GOOGLE_APP_SCRIPT_API_CLIENT_SECRET=your_client_secret_here

# Optional: Logging level
LOG_LEVEL=info

OAuth Authentication Setup

npm run setup-oauth

Test Your Setup

npm start

💻 Usage Examples

Testing the Server

npm start

Testing OAuth Authentication

npm run test-oauth

Listing Available Tools

npm run list-tools

📚 Documentation

Available Tools

This MCP server provides 16 comprehensive tools for Google Apps Script management.

Project Management Tools

• script-projects-create: Create a new Google Apps Script project
• script-projects-get: Get metadata of a Google Apps Script project
• script-projects-get-content: Get the content of a Google Apps Script project
• script-projects-update-content: Update the content of a Google Apps Script project

Version Management Tools

• script-projects-versions-create: Create a new version of a Google Apps Script project
• script-projects-versions-get: Get details of a specific script version
• script-projects-versions-list: List all versions of a script project

Deployment Management Tools

• script-projects-deployments-create: Create a deployment of a Google Apps Script project
• script-projects-deployments-get: Get details of a specific deployment
• script-projects-deployments-list: List all deployments of a script project
• script-projects-deployments-update: Update an existing deployment
• script-projects-deployments-delete: Delete a deployment

Execution and Monitoring Tools

• script-scripts-run: Execute a Google Apps Script function
• script-processes-list: List execution processes for a script project
• script-processes-list-script-processes: Alternative method to list script processes with additional filtering
• script-projects-get-metrics: Get execution metrics and analytics for a script project

Tool Categories Summary

Common Use Cases

Development Workflow

1. Use script-projects-create to create new projects
2. Use script-projects-update-content to upload code
3. Use script-projects-versions-create to create stable versions
4. Use script-projects-deployments-create to deploy for production

Monitoring and Debugging

1. Use script-processes-list to see execution history
2. Use script-projects-get-metrics to analyze performance
3. Use script-projects-get-content to backup source code

Production Management

1. Use script-projects-deployments-list to see all deployments
2. Use script-projects-deployments-update to update production configs
3. Use script-scripts-run to trigger automated workflows

MCP Client Configuration

Getting Required Paths

Before configuring any MCP client, you'll need the absolute paths to Node.js and your mcpServer.js file.

Connecting to Claude Desktop

{
  "mcpServers": {
    "google-apps-script": {
      "command": "<absolute_path_to_node_executable>",
      "args": ["<absolute_path_to_mcpServer.js>"],
      "env": {
        "GOOGLE_APP_SCRIPT_API_CLIENT_ID": "your_client_id_here",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Connecting to VS Code

{
  "cline.mcpServers": {
    "google-apps-script": {
      "command": "C:\\nvm4w\\nodejs\\node.exe",
      "args": ["C:\\Users\\mohal\\Downloads\\google-appscriot-mcp-server\\mcpServer.js"],
      "env": {
        "GOOGLE_APP_SCRIPT_API_CLIENT_ID": "your_client_id_here",
        "GOOGLE_APP_SCRIPT_API_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

🔧 Technical Details

Environment Variables

# Required OAuth credentials
GOOGLE_APP_SCRIPT_API_CLIENT_ID=your_client_id
GOOGLE_APP_SCRIPT_API_CLIENT_SECRET=your_client_secret

# Optional configuration
LOG_LEVEL=info                    # debug, info, warn, error
NODE_ENV=development              # development, production
PORT=3001                        # OAuth callback port

Running in Production

Using PM2 Process Manager

# Install PM2
npm install -g pm2

# Start with PM2
pm2 start mcpServer.js --name "gas-mcp-server"

# Monitor
pm2 status
pm2 logs gas-mcp-server

# Auto-restart on system boot
pm2 startup
pm2 save

Using Docker

docker build -t google-apps-script-mcp .
docker run -i --rm --env-file=.env google-apps-script-mcp

Custom Tool Development

Adding New Tools

1. Create a new tool file in tools/google-app-script-api/apps-script-api/
2. Add to paths.js
3. Update tool descriptions in your MCP server tool definitions

Performance Optimization

Token Caching

The OAuth helper automatically caches access tokens in memory and refreshes them as needed.

Request Batching

const results = await Promise.all([
  tool1(args1),
  tool2(args2),
  tool3(args3)
]);

Rate Limiting

Google Apps Script API has rate limits. The tools include automatic retry logic with exponential backoff.

Security Best Practices

Credential Management

• Never commit .env files to version control
• Use different OAuth apps for development and production
• Regularly rotate OAuth credentials
• Monitor OAuth app usage in Google Cloud Console

Access Control

• Use least-privilege OAuth scopes
• Add only necessary test users to your OAuth app
• Monitor script execution logs for unauthorized access
• Implement logging for all API calls

Network Security

• Run the MCP server in a secure environment
• Use HTTPS for production deployments
• Implement proper firewall rules
• Monitor network traffic for anomalies

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.