Google MCP

🚀 Google MCP Server

A comprehensive Model Context Protocol (MCP) server that offers access to Google services, such as 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

📚 Documentation

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.

🔧 Technical Details

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]