Distance Calculator MCP server

This project calculates the distance between two locations using the Google Distance Matrix API.

Setup

1. Install the dependencies:

   uv sync

2. Configure your Google Maps API key:

   Environment Variable (Recommended)

   export GOOGLE_API_KEY=your_google_maps_api_key_here

   Or create a .env file:

   cp .env.example .env
   # Edit .env and replace your_google_maps_api_key_here with your actual key

3. Get your Google Maps API Key:

   • Go to Google Cloud Console
   • Create a new project or select an existing one
   • Enable the "Distance Matrix API"
   • Create credentials (API key)
   • Copy the API key for use in step 2

Running the Application

Option 1: Using Docker (Recommended)

# Build the Docker image
docker build -t distance-calculator .

# Run MCP Server (default)
docker run -p 8001:8001 -e GOOGLE_API_KEY=your_api_key distance-calculator

# Run REST API Server
docker run -p 8000:8000 -e GOOGLE_API_KEY=your_api_key distance-calculator uv run python scripts/run_rest_server.py

# Or use docker-compose for both services
docker-compose up

Option 2: Using Scripts (Local Development)

# REST API Server
uv run python scripts/run_rest_server.py

# MCP Server
uv run python scripts/run_mcp_server.py

Option 3: Direct Module Execution

# REST API Server
uv run python -m src.distance_calculator.servers.rest_server

# MCP Server
uv run python -m src.distance_calculator.servers.mcp_server

The REST API will be available at http://127.0.0.1:8000.

Integration with AI Tools

Claude Desktop

Add this to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "distance-calculator": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GOOGLE_API_KEY=<YOUR_GOOGLE_MAPS_API_KEY>",
        "distance-calculator"
      ]
    }
  }
}

Cursor

Add this to your Cursor MCP settings:

1. Open Cursor Settings
2. Go to "Features" → "Model Context Protocol"
3. Add a new server with this configuration:

{
  "distance-calculator": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "GOOGLE_API_KEY=<YOUR_GOOGLE_MAPS_API_KEY>",
      "distance-calculator"
    ]
  }
}

Note: Replace <YOUR_GOOGLE_MAPS_API_KEY> with your actual Google Maps API key.

API Usage

Send a POST request to /distance with a JSON payload like this:

{
  "origin": {
    "location": "90210"
  },
  "destination": {
    "location": "New York, NY"
  }
}

Development

Running Tests

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=src

# Run specific test file
uv run pytest tests/test_distance_service.py -v

Code Quality

# Format code
uv run black src/ tests/ scripts/

# Check code style
uv run flake8 src/ tests/ scripts/

# Type checking
uv run mypy src/

Example with gemini CLI

commute-calculator-mcp