Google Docs MCP Server

Fork of lkm1developer/google-docs-mcp-server

This fork adds Markdown export functionality using Google's native conversion.

A powerful Model Context Protocol (MCP) server implementation for seamless Google Docs API integration, enabling AI assistants to create, read, update, and manage Google Docs.

Recommended Production Configuration

Full server start command via STDIO:

npx -y @brdemorin/google-docs-mcp-server

Environment Variables:

GOOGLE_CLOUD_PROJECT_ID=your-project-id
GOOGLE_APPLICATION_CREDENTIALS=path/to/your-service-account-key.json

MCP Config:

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@brdemorin/google-docs-mcp-server"],
      "env": {
        "GOOGLE_CLOUD_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "path/to/your-service-account-key.json"
      }
    }
  }
}

What's New in This Fork

• google_docs_to_markdown - Export any Google Doc to Markdown format using Google's native conversion (not custom parsing)

Features

• Export documents to Markdown (new in this fork)
• Create new Google Docs with custom titles and content
• Retrieve document content and metadata
• Update existing documents with new content
• List all accessible documents
• Delete documents
• Export documents to different formats (PDF, plain text, etc.)
• Share documents with specific users
• Search for documents by title or content
• Verify connection and credentials

Prerequisites

• Node.js 18 or higher
• A Google Cloud project with the Google Docs API enabled
• Authentication credentials (API key, service account, or OAuth2)

Installation

Option 1: npm (Recommended)

npx -y @brdemorin/google-docs-mcp-server

Option 2: From Source

1. Clone this repository:

   git clone https://github.com/brdemorin/google-docs-mcp-server.git
   cd google-docs-mcp-server

2. Install dependencies:

   npm install

3. Create a .env file with your Google Cloud credentials:

   # Required
   GOOGLE_CLOUD_PROJECT_ID=your-project-id
      
   # Choose one authentication method:
      
   # Option 1A: Service Account with file path (recommended for production)
   GOOGLE_APPLICATION_CREDENTIALS=path/to/your-service-account-key.json
      
   # Option 1B: Service Account with JSON content directly
   # Useful for environments where you can't create files
   GOOGLE_APPLICATION_CREDENTIALS_JSON={"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}
      
   # Option 2: API Key (simpler for development)
   GOOGLE_API_KEY=your-api-key
      
   # Option 3: OAuth2 (required for user-specific operations)
   client_id=your-oauth-client-id
   client_secret=your-oauth-client-secret
   refresh_token=your-oauth-refresh-token

Authentication Setup

Service Account Authentication

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Docs API and Google Drive API:
   • Go to "APIs & Services" > "Library"
   • Search for "Google Docs API" and click "Enable"
   • Search for "Google Drive API" and click "Enable"
4. Go to "IAM & Admin" > "Service Accounts"
5. Create a new service account
6. Create and download a JSON key for the service account
7. Set the path to this JSON file in your environment as GOOGLE_APPLICATION_CREDENTIALS
8. Important: Share your Google Drive folder/documents with the service account:
   • Find the service account email in the JSON key file (looks like [email protected])
   • Go to Google Drive and right-click the folder or document you want to access
   • Click "Share" and add the service account email address
   • Set permission to Editor (required for create/update operations)

OAuth2 Authentication

For operations that require user consent (like creating/editing documents):

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Docs API and Google Drive API
4. Go to "APIs & Services" > "Credentials"
5. Create OAuth client ID credentials (Web application type)
6. Add authorized redirect URIs (e.g., http://localhost:3000/oauth2callback)
7. Note your Client ID and Client Secret
8. Use the following script to get a refresh token:

// get-refresh-token.js
const { google } = require('googleapis');
const http = require('http');
const url = require('url');
const open = require('open');
const destroyer = require('server-destroy');

async function getRefreshToken() {
  const oauth2Client = new google.auth.OAuth2(
    'YOUR_CLIENT_ID',
    'YOUR_CLIENT_SECRET',
    'http://localhost:3000/oauth2callback'
  );

  const scopes = [
    'https://www.googleapis.com/auth/documents',
    'https://www.googleapis.com/auth/drive'
  ];

  const authorizeUrl = oauth2Client.generateAuthUrl({
    access_type: 'offline',
    scope: scopes,
    prompt: 'consent'
  });

  console.log('Opening browser for authorization...');
  open(authorizeUrl);

  return new Promise((resolve, reject) => {
    const server = http.createServer(async (req, res) => {
      try {
        const queryParams = url.parse(req.url, true).query;
        
        if (queryParams.code) {
          res.end('Authentication successful! You can close this window.');
          server.destroy();
          
          const { tokens } = await oauth2Client.getToken(queryParams.code);
          console.log('\nRefresh Token:', tokens.refresh_token);
          console.log('\nAdd this refresh token to your .env file as refresh_token');
          
          resolve(tokens.refresh_token);
        }
      } catch (e) {
        reject(e);
      }
    }).listen(3000);
    
    destroyer(server);
  });
}

getRefreshToken().catch(console.error);

Run this script with:

npm install googleapis open server-destroy
node get-refresh-token.js

Building and Running

1. Build the project:

   npm run build

2. Test your connection:

   npx tsx src/test-connection.ts

3. Run the server:

   npm start

   Or with specific credentials:

   npm start -- --GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json --GOOGLE_CLOUD_PROJECT_ID=your-project-id
      
   # Or with JSON content directly:
   npm start -- --GOOGLE_APPLICATION_CREDENTIALS_JSON='{"type":"service_account","project_id":"..."}' --GOOGLE_CLOUD_PROJECT_ID=your-project-id

4. Run the SSE server with authentication:

   npx mcp-proxy-auth node dist/index.js

Implementing Authentication in SSE Server

The SSE server uses the mcp-proxy-auth package for authentication. To implement authentication:

1. Install the package:

   npm install mcp-proxy-auth

2. Set the AUTH_SERVER_URL environment variable to point to your API key verification endpoint:

   export AUTH_SERVER_URL=https://your-auth-server.com/verify

3. Run the SSE server with authentication:

   npx mcp-proxy-auth node dist/index.js

4. The SSE URL will be available at:

   localhost:8080/sse?apiKey=apikey

   Replace apikey with your actual API key for authentication.

The mcp-proxy-auth package acts as a proxy that:

• Intercepts requests to your SSE server
• Verifies API keys against your authentication server
• Only allows authenticated requests to reach your SSE endpoint

Docker Support

You can also run the server using Docker:

1. Build the Docker image:

   docker build -t google-docs-mcp-server .

2. Run the container:

   docker run -p 8080:8080 \
     -e GOOGLE_CLOUD_PROJECT_ID=your-project-id \
     -e GOOGLE_APPLICATION_CREDENTIALS_JSON='{"type":"service_account","project_id":"..."}' \
     -e client_id=your-client-id \
     -e client_secret=your-client-secret \
     -e refresh_token=your-refresh-token \
     -e AUTH_SERVER_URL=https://your-auth-server.com/verify \
     google-docs-mcp-server

MCP Integration

To use this server with Claude or other MCP-compatible assistants, add it to your MCP settings:

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@brdemorin/google-docs-mcp-server"],
      "env": {
        "GOOGLE_CLOUD_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your-service-account-key.json"
      }
    }
  }
}

Or with OAuth credentials:

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@brdemorin/google-docs-mcp-server"],
      "env": {
        "client_id": "your-oauth-client-id",
        "client_secret": "your-oauth-client-secret",
        "refresh_token": "your-oauth-refresh-token"
      }
    }
  }
}

Available Tools

| Tool Name | Description | Required Parameters | |-----------|-------------|---------------------| | google_docs_create | Create a new Google Doc | title, content (optional) | | google_docs_update | Update a Google Doc with new content | documentId, content, replaceAll (optional) | | google_docs_list | List Google Docs accessible to the authenticated user | pageSize (optional), pageToken (optional) | | google_docs_delete | Delete a Google Doc | documentId | | google_docs_export | Export a Google Doc to different formats | documentId, mimeType (optional) | | google_docs_to_markdown | Export a Google Doc to Markdown format | documentId, markdownOnly (optional) | | google_docs_share | Share a Google Doc with specific users | documentId, emailAddress, role (optional) | | google_docs_search | Search for Google Docs by title or content | query, pageSize (optional), pageToken (optional) | | google_docs_verify_connection | Verify connection with Google Docs API | None |

Example Usage

Here are some examples of how to use the tools:

Create a new document

{
  "name": "google_docs_create",
  "arguments": {
    "title": "My New Document",
    "content": "This is the content of my new document."
  }
}

Export to Markdown

{
  "name": "google_docs_to_markdown",
  "arguments": {
    "documentId": "1Ax7vsdg3_YhKjkl2P0TZ5XYZ123456"
  }
}

Update a document

{
  "name": "google_docs_update",
  "arguments": {
    "documentId": "1Ax7vsdg3_YhKjkl2P0TZ5XYZ123456",
    "content": "This is the new content.",
    "replaceAll": true
  }
}

Search for documents

{
  "name": "google_docs_search",
  "arguments": {
    "query": "meeting notes",
    "pageSize": 5
  }
}

License

MIT