Gmail & PostgreSQL MCP Server

# 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. ## 🚀 Two Modes Available ### 1. **stdio Mode** (for Claude Desktop) - Direct integration with Claude Desktop - Uses standard input/output - No network configuration needed ### 2. **HTTP/SSE Mode** (for n8n, remote agents) - HTTP server with Server-Sent Events (SSE) - Can be deployed to VPS - Accessible via URL - **Perfect for n8n AI Agent with MCP Client connector** ## 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:** ```bash npm install ``` 2. **Build the project:** ```bash npm run build ``` ## Configuration ### Step 1: Create `.env` file Copy the example file and fill in your credentials: ```bash cp .env.example .env ``` ### Step 2: Configure Gmail #### Get Gmail API Credentials 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 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: ```bash 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`: ```env GMAIL_CLIENT_ID=your_client_id_from_step_5 GMAIL_CLIENT_SECRET=your_client_secret_from_step_5 GMAIL_REFRESH_TOKEN=your_refresh_token_from_step_6 ``` ### Step 3: Configure PostgreSQL Add your PostgreSQL connection details to `.env`: ```env POSTGRES_HOST=localhost # or your database host POSTGRES_PORT=5432 # default PostgreSQL port POSTGRES_DATABASE=your_db_name # your database name POSTGRES_USER=your_db_user # your database user POSTGRES_PASSWORD=your_password # your database password POSTGRES_SSL=false # set to true if using SSL ``` ## Usage ### For n8n (HTTP Mode) - **RECOMMENDED** Start the HTTP server: ```bash # Development npm run dev:http # Production npm run build npm run start:http ``` Server will be available at: `http://localhost:3000/sse` **See [N8N_SETUP.md](N8N_SETUP.md) for complete n8n integration guide.** ### For Claude Desktop (stdio Mode) ```bash # Development npm run dev # Production npm start ``` Configure in Claude Desktop's config file (see Configuration section below). ## 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:** ```bash scp -r . user@your-vps-ip:/path/to/mcp-server/ ``` 2. **SSH into your VPS and install:** ```bash ssh user@your-vps-ip cd /path/to/mcp-server npm install npm run build ``` 3. **Create `.env` file on VPS** with your credentials 4. **Run as a service (using PM2 or systemd):** With PM2: ```bash npm install -g pm2 pm2 start npm --name "mcp-server" -- start pm2 save ``` With systemd, create `/etc/systemd/system/mcp-server.service`: ```ini [Unit] Description=MCP Gmail & PostgreSQL Server After=network.target [Service] Type=simple User=your-user WorkingDirectory=/path/to/mcp-server Environment=NODE_ENV=production ExecStart=/usr/bin/node dist/index.js Restart=always [Install] WantedBy=multi-user.target ``` Then: ```bash sudo systemctl enable mcp-server sudo systemctl start mcp-server ``` ## Project Structure ``` . ├── src/ │ ├── index.ts # Main server entry point │ └── services/ │ ├── gmail.service.ts # Gmail integration │ └── postgres.service.ts # PostgreSQL integration ├── dist/ # Compiled JavaScript ├── .env # Environment variables (not in git) ├── .env.example # Example environment file ├── package.json ├── tsconfig.json └── README.md ``` ## 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