MCP Gmail & PostgreSQL Server

A unified Model Context Protocol (MCP) server that provides AI agents with read and write access to Gmail and PostgreSQL databases.

Features

• Gmail Integration: Send emails, read emails, list emails, and manage labels

• PostgreSQL Integration: Execute queries, read/write operations, and schema inspection

• Modular Architecture: Cleanly separated services for easy maintenance

• Environment-based Configuration: Secure credential management via .env file

Prerequisites

• Node.js 18+

• npm or yarn

• Gmail API credentials (Google Cloud Console)

• PostgreSQL database

Installation

1. Clone and install dependencies:

2. Build the project:

Configuration

Step 1: Create .env file

Copy the example file and fill in your credentials:

Step 2: Configure Gmail

Get Gmail API Credentials

1. Go to Google Cloud Console

2. Create a new project or select an existing one

3. Enable the Gmail API:

   • Navigate to "APIs & Services" > "Library"

   • Search for "Gmail API" and click "Enable"

4. Create OAuth 2.0 credentials:

   • Go to "APIs & Services" > "Credentials"

   • Click "Create Credentials" > "OAuth client ID"

   • Choose "Desktop app" as application type

   • Download the credentials JSON file

5. Get your Client ID and Client Secret from the credentials

6. Get a Refresh Token:

   • Run this script to authorize and get a refresh token:

   node scripts/get-gmail-token.js

   • Or use Google's OAuth 2.0 Playground:

     1. Go to https://developers.google.com/oauthplayground/

     2. Click the gear icon (⚙️) and check "Use your own OAuth credentials"

     3. Enter your Client ID and Client Secret

     4. In the left panel, select "Gmail API v1" and check the scopes:

        • https://www.googleapis.com/auth/gmail.readonly

        • https://www.googleapis.com/auth/gmail.send

        • https://www.googleapis.com/auth/gmail.modify

     5. Click "Authorize APIs" and sign in

     6. Click "Exchange authorization code for tokens"

     7. Copy the "Refresh token" value

7. Add to .env:

Step 3: Configure PostgreSQL

Add your PostgreSQL connection details to .env:

Usage

Development Mode

Production Mode

The server runs on stdio and communicates via JSON-RPC, following the MCP protocol.

Available Tools

Gmail Tools

• gmail_list_emails: List emails from inbox with optional filters

  • Parameters: query, maxResults, labelIds

• gmail_read_email: Read a specific email by message ID

  • Parameters: messageId, format

• gmail_send_email: Send an email

  • Parameters: to, subject, body, htmlBody (optional), cc (optional), bcc (optional)

• gmail_get_labels: Get all Gmail labels

PostgreSQL Tools

• postgres_query: Execute SELECT queries (read-only)

  • Parameters: query, params (optional array)

• postgres_execute: Execute write operations (INSERT, UPDATE, DELETE)

  • Parameters: query, params (optional array)

• postgres_get_tables: List all tables in the database

  • Parameters: schema (optional, default: 'public')

• postgres_get_table_schema: Get schema information for a table

  • Parameters: tableName, schema (optional, default: 'public')

Deployment to VPS

1. Transfer files to your VPS:

2. SSH into your VPS and install:

3. Create with your credentials

4. Run as a service (using PM2 or systemd):

With PM2:

With systemd, create /etc/systemd/system/mcp-server.service:

Then:

Project Structure

Security Notes

• Never commit .env file to version control

• Use strong database passwords

• Keep Gmail OAuth credentials secure

• Consider using environment-specific credentials for production

• Regularly rotate refresh tokens and passwords

Troubleshooting

Gmail not working

• Verify your refresh token is valid and not expired

• Check that all required OAuth scopes are granted

• Ensure GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET are correct

PostgreSQL connection issues

• Verify database credentials are correct

• Check if PostgreSQL is running and accessible

• For remote connections, ensure firewall rules allow connections

• If using SSL, set POSTGRES_SSL=true in .env

License

MIT