Globalping

# Globalping MCP Server

<p align="center">
  <img src="https://raw.githubusercontent.com/jsdelivr/globalping-media/refs/heads/master/logo/full_colored_dark.svg" alt="Globalping Logo" width="180"/>
</p>

<p align="center">
  <b>Enable AI models to interact with a global network measurement platform through natural language. Give network access to any LLM.</b>
</p>

<p align="center">
  <a href="https://github.com/modelcontextprotocol/modelcontextprotocol">
    <img src="https://img.shields.io/badge/MCP-compatible-brightgreen.svg" alt="MCP Compatible">
  </a>
</p>


## What is Globalping?

[Globalping](https://globalping.io) is a free, public API that provides access to a globally distributed network of probes for monitoring, debugging, and benchmarking internet infrastructure. With Globalping, you can run network tests (ping, traceroute, DNS, MTR, HTTP) from thousands of locations worldwide.


## What is the Globalping MCP Server?

The Globalping MCP Server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), allowing AI models like OpenAI's GPT and Anthropic's Claude to interact with Globalping's network measurement capabilities through natural language.

It also supports two authentication methods: OAuth and API token authentication. Both methods offer a secure way to interact with our API and provide higher rate limits associated with your account.

### Key Features

- 🌐 **Global Network Access**: Run measurements from thousands of probes worldwide
- 🤖 **AI-Friendly Interface**: Any LLM will easily parse the data and run new measurements as needed
- 📊 **Comprehensive Measurements**: Support for ping, traceroute, DNS, MTR, and HTTP tests
- 🔍 **Smart Context Handling**: Provides detailed parameter descriptions for AI clients to intelligently select measurement types and options
- 🔄 **Comparative Analysis**: Allows to compare network performance between different targets
- 🔑 **Authentication Support**: Use OAuth or API token with your Globalping account for higher rate limits


## Installation

The remote MCP server is available under these endpoints:
- Streamable HTTP transport: `https://mcp.globalping.dev/mcp`
- SSE transport: `https://mcp.globalping.dev/sse`

You can integrate our Globalping MCP server with various AI tools that support the Model Context Protocol. 

Here are instructions for the top 3 most popular tools:

#### Gemini CLI

To add the Globalping MCP server to Gemini CLI:

1. Ensure you have the [Gemini CLI](https://github.com/google/gemini-cli) installed.
2. Run the following command:

```bash
gemini extensions install https://github.com/jsdelivr/globalping-mcp-server
```

This will automatically configure the server with OAuth authentication enabled. You will be prompted to log in when you first use the extension.

**Note:** If you prefer to use a Globalping API token (for higher rate limits or automation), you can manually add the server with the Authorization header instead of using the extension installer:

```bash
gemini mcp add globalping https://mcp.globalping.dev/mcp --header "Authorization: Bearer YOUR_TOKEN"
```

#### Claude Desktop App

Add to your Claude Desktop configuration file (located at `%APPDATA%\Claude\config.json` on Windows or `~/Library/Application Support/Claude/config.json` on macOS):

> [!note]
> Claude Desktop natively supports only stdio transport for local MCP servers.
> For remote MCP servers, use the `mcp-remote` bridge.

```json
{
    "mcpServers": {
        "globalping": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.globalping.dev/sse"
            ]
        }
    }
}
```
#### Anthropic Claude API (via Console)

When creating a Claude Assistant in the Anthropic Console:

1. Go to [console.anthropic.com](https://console.anthropic.com/)
2. Navigate to the Assistants section
3. Create a new Assistant or edit an existing one
4. In the Tools section, select "Add custom tool"
5. Enter the following details:
   - Tool Name: `Globalping`
   - Description: `Run network tests from locations worldwide`
   - Tool URL: `https://mcp.globalping.dev/mcp` (Streamable HTTP transport) or `https://mcp.globalping.dev/sse` (SSE transport)

#### Cursor

To add the Globalping MCP server to Cursor:

1. Open Cursor settings
2. Navigate to the Tools & MCP tab
3. Click on "+ New MCP server"
4. This opens the `mcp.json` config file, where you will need to add:

Streamable HTTP transport:
```json
{
    "mcpServers": {
        "globalping": {
            "url": "https://mcp.globalping.dev/mcp"
        }
    }
}
```
Legacy SSE transport:
```json
{
    "mcpServers": {
        "globalping": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.globalping.dev/sse"
            ]
        }
    }
}
```
5. Save and restart Cursor
## Authentication

The Globalping MCP server supports two authentication methods:
- **OAuth Authentication**: Automatically handled by the server for secure access
- **API Token Authentication**: Manual token configuration via Authorization header

Both methods provide higher rate limits and priority access to the probe network.

### Using Globalping API Token

The server automatically detects when an API token is provided in the Authorization header and uses it for authentication instead of OAuth.

#### Getting Your API Token

1. Visit [dash.globalping.io](https://dash.globalping.io)
2. Sign in to your account
3. Navigate to Tokens to generate a new API token

#### Configuration with Authentication

Streamable HTTP transport:
```json
{
    "mcpServers": {
        "globalping": {
            "url": "https://mcp.globalping.dev/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_GLOBALPING_API_TOKEN"
            }
        }
    }
}
```
Legacy SSE transport:
```json
{
    "mcpServers": {
        "globalping": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.globalping.dev/sse",
                "--header",
                "Authorization: Bearer YOUR_GLOBALPING_API_TOKEN"
            ]
        }
    }
}
```

## Connecting AI Assistants

You can use our MCP server with any MCP-compatible AI assistant, including:

- Claude Desktop
- Anthropic Assistants
- Cursor
- Windsurf
- Any custom implementation of the MCP protocol

See your tool's MCP documentation for details on connecting clients to this server.


## Available Tools

- `ping` - Perform a ping test to a target
- `traceroute` - Perform a traceroute test to a target
- `dns` - Perform a DNS lookup for a domain
- `mtr` - Perform an MTR (My Traceroute) test to a target
- `http` - Perform an HTTP request to a URL
- `locations` - List all available Globalping probe locations
- `limits` - Show your current rate limits for the Globalping API
- `getMeasurement` - Retrieve a previously run measurement by ID
- `compareLocations` - Guide on how to run comparison measurements
- `help` - Show a help message with documentation on available tools

## Usage Examples

Once connected to an AI model through a compatible MCP client, you can interact with Globalping using natural language:

```
Ping google.com from 3 locations in Europe
```

```
Run a traceroute to github.com from Japan and compare with traceroute from the US
```

```
Check the DNS resolution of example.com using Google DNS (8.8.8.8)
```

```
Is jsdelivr.com reachable from China? Test with both ping and HTTP
```

```
What's the average response time for cloudflare.com across different continents?
```


## Location Specification

Locations can be specified using the "magic" field, which supports various formats:

- Continent codes: "EU", "NA", "AS", etc.
- Country codes: "US", "DE", "JP", etc.
- City names: "London", "Tokyo", "New York", etc.
- Network names: "Cloudflare", "Google", etc.
- ASN numbers: "AS13335", "AS15169", etc.
- Cloud provider regions: "aws-us-east-1", "gcp-us-central1", etc.

You can also combine these with a plus sign for more specific targeting: "London+UK", "Cloudflare+US", etc.


## Development

The codebase is organized into modules:

- `src/index.ts` - Main entry point and MCP agent definition
- `src/app.ts` - OAuth web routes
- `src/api` - Globalping API client
- `src/auth` - Authentication utilities
- `src/config` - Configuration and constants
- `src/lib` - Utility functions
- `src/mcp` - MCP tool handlers
- `src/types` - TypeScript type definitions
- `src/ui` - HTML templates


### Add Globalping credentials

Add Globalping OAuth credentials:

- `npx wrangler secret put GLOBALPING_CLIENT_ID`

### KV storage
Used for `OAuthProvider` docs https://github.com/cloudflare/workers-oauth-provider
- create a KV namespace and copy ID
- binding for it must be `OAUTH_KV`
- configure `kv_namespaces` in the `wrangler.jsonc` file