Google MCP Server

A comprehensive Model Context Protocol (MCP) server that provides access to Google services including Maps, Finance, Flights, Gmail, and Calendar through a unified API.

Features

🗺️ Google Maps & Places

• Geocoding: Convert addresses to coordinates and vice versa
• Places Search: Find businesses, landmarks, and points of interest
• Directions: Get turn-by-turn directions between locations
• Distance Matrix: Calculate travel time and distance between multiple points
• Place Details: Get detailed information about specific places

📈 Google Finance

• Stock Search: Search for stocks, indices, mutual funds, currencies, and futures
• Market Data: Get current prices, movement, and market information
• Financial News: Access top financial news related to securities

✈️ Google Flights

• Airport Search: Find flights and airport information
• Flight Pricing: Get flight prices and insights
• Multi-city Trips: Support for complex multi-destination journeys

📧 Gmail

• Send Emails: Send emails with subject, body, CC, and BCC
• Read Emails: List and search emails with Gmail query syntax
• Email Details: Get full email content by message ID
• Label Management: Access Gmail labels and organization

📅 Google Calendar

• Event Management: Create, read, update, and delete calendar events
• Multi-Calendar Support: Work with multiple calendars (Personal, Work, Travel)
• Event Listing: List events with filters and date ranges
• Calendar Management: List and access different calendars

Installation

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm

Setup

1. Clone the repository:

   git clone <repository-url>
   cd google-mcp

2. Install dependencies:

   pnpm install

3. Build the project:

   pnpm run build

MCP Client Integration

Install the server to your preferred MCP clients:

# Install to all MCP clients
pnpm run install-server

# Install to specific clients
pnpm run install-desktop    # Claude Desktop
pnpm run install-cursor     # Cursor IDE
pnpm run install-code       # Claude Code
pnpm run install-mcp        # Local .mcp.json only

Configuration

Environment Variables

Create a .env.local file in the project root with your Google API credentials:

GOOGLE_MAPS_API_KEY=your_google_maps_api_key
GOOGLE_CLIENT_ID=your_oauth_client_id
GOOGLE_CLIENT_SECRET=your_oauth_client_secret
GOOGLE_REFRESH_TOKEN=your_refresh_token

Google API Setup

1. Google Maps API: Enable Maps, Places, and Directions APIs in Google Cloud Console
2. Gmail/Calendar: Set up OAuth 2.0 credentials and obtain refresh tokens
3. Finance/Flights: Uses Google's public APIs (no additional setup required)

Usage

Running the Server

# Start the compiled server
pnpm start

# Or run in development mode
node dist/index.js

Available Tools

Maps & Places

• geocode - Convert address to coordinates
• reverse-geocode - Convert coordinates to address
• places-search - Search for places by text query
• get-directions - Get directions between locations
• distance-matrix - Calculate distances between multiple points
• place-details - Get detailed place information

Finance

• finance-search - Search stocks, currencies, and financial instruments

Flights

• airports-search - Search flights and airport information

Gmail

• gmail-send-email - Send emails
• gmail-read-emails - List/search emails
• gmail-get-email - Get specific email by ID
• gmail-get-labels - List Gmail labels

Calendar

• calendar-create-event - Create new events
• calendar-list-events - List events with filters
• calendar-get-event - Get specific event details
• calendar-update-event - Update existing events
• calendar-delete-event - Delete events
• calendar-list-calendars - List available calendars

Development

Project Structure

src/
├── index.ts       # Main MCP server implementation
├── maps.ts        # Google Maps & Places functionality
├── finance.ts     # Google Finance integration
├── airports.ts    # Google Flights integration  
├── gmail.ts       # Gmail API integration
└── calendar.ts    # Google Calendar integration

scripts/
└── update-config.js   # MCP client configuration installer

dist/             # Compiled JavaScript output

Key Technologies

• MCP SDK: @modelcontextprotocol/sdk for protocol implementation
• Schema Validation: Zod for runtime type checking
• Google APIs: Official Google client libraries
• TypeScript: Full type safety with ES2022 target
• Transport: StdioServerTransport for MCP communication

Development Workflow

1. Make changes to TypeScript files in src/
2. Build: pnpm run build
3. Test: pnpm start
4. Install to clients: pnpm run install-server
5. Restart MCP clients to load changes

Adding New Tools

1. Define Zod schema for parameters
2. Implement handler function
3. Register tool in src/index.ts using server.tool()
4. Build and reinstall to test

Architecture

This MCP server follows these design patterns:

• Modular Design: Each Google service is in its own module
• Schema Validation: All parameters validated with Zod schemas
• Error Handling: Comprehensive error handling with meaningful messages
• Type Safety: Full TypeScript coverage with strict mode
• Transport Agnostic: Uses MCP's standard transport layer

License

[License information]

Contributing

[Contribution guidelines]