Globalping MCP Server

1# Globalping MCP Server
2 
3<p align="center">
4  <img src="https://raw.githubusercontent.com/jsdelivr/globalping-media/refs/heads/master/logo/full_colored_dark.svg" alt="Globalping Logo" width="180"/>
5</p>
6 
7<p align="center">
8  <b>Enable AI models to interact with a global network measurement platform through natural language. Give network access to any LLM.</b>
9</p>
10 
11<p align="center">
12  <a href="https://github.com/modelcontextprotocol/modelcontextprotocol">
13    <img src="https://img.shields.io/badge/MCP-compatible-brightgreen.svg" alt="MCP Compatible">
14  </a>
15</p>
16 
17 
18## What is Globalping?
19 
20[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.
21 
22 
23## What is the Globalping MCP Server?
24 
25The 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.
26 
27It 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.
28 
29### Key Features
30 
31- 🌐 **Global Network Access**: Run measurements from thousands of probes worldwide
32- 🤖 **AI-Friendly Interface**: Any LLM will easily parse the data and run new measurements as needed
33- 📊 **Comprehensive Measurements**: Support for ping, traceroute, DNS, MTR, and HTTP tests
34- 🔍 **Smart Context Handling**: Provides detailed parameter descriptions for AI clients to intelligently select measurement types and options
35- 🔄 **Comparative Analysis**: Allows to compare network performance between different targets
36- 🔑 **Authentication Support**: Use OAuth or API token with your Globalping account for higher rate limits
37 
38 
39## Installation
40 
41The remote MCP server is available under these endpoints:
42- Streamable HTTP transport: `https://mcp.globalping.dev/mcp`
43- SSE transport: `https://mcp.globalping.dev/sse`
44 
45You can integrate our Globalping MCP server with various AI tools that support the Model Context Protocol. 
46 
47Here are instructions for the top 3 most popular tools:
48 
49#### Gemini CLI
50 
51To add the Globalping MCP server to Gemini CLI:
52 
531. Ensure you have the [Gemini CLI](https://github.com/google/gemini-cli) installed.
542. Run the following command:
55 
56```bash
57gemini extensions install https://github.com/jsdelivr/globalping-mcp-server
58```
59 
60This will automatically configure the server with OAuth authentication enabled. You will be prompted to log in when you first use the extension.
61 
62**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:
63 
64```bash
65gemini mcp add globalping https://mcp.globalping.dev/mcp --header "Authorization: Bearer YOUR_TOKEN"
66```
67 
68#### Claude Desktop App
69 
70Add to your Claude Desktop configuration file (located at `%APPDATA%\Claude\config.json` on Windows or `~/Library/Application Support/Claude/config.json` on macOS):
71 
72> [!note]
73> Claude Desktop natively supports only stdio transport for local MCP servers.
74> For remote MCP servers, use the `mcp-remote` bridge.
75 
76```json
77{
78    "mcpServers": {
79        "globalping": {
80            "command": "npx",
81            "args": [
82                "mcp-remote",
83                "https://mcp.globalping.dev/sse"
84            ]
85        }
86    }
87}
88```
89#### Anthropic Claude API (via Console)
90 
91When creating a Claude Assistant in the Anthropic Console:
92 
931. Go to [console.anthropic.com](https://console.anthropic.com/)
942. Navigate to the Assistants section
953. Create a new Assistant or edit an existing one
964. In the Tools section, select "Add custom tool"
975. Enter the following details:
98   - Tool Name: `Globalping`
99   - Description: `Run network tests from locations worldwide`
100   - Tool URL: `https://mcp.globalping.dev/mcp` (Streamable HTTP transport) or `https://mcp.globalping.dev/sse` (SSE transport)
101 
102#### Cursor
103 
104To add the Globalping MCP server to Cursor:
105 
1061. Open Cursor settings
1072. Navigate to the Tools & MCP tab
1083. Click on "+ New MCP server"
1094. This opens the `mcp.json` config file, where you will need to add:
110 
111Streamable HTTP transport:
112```json
113{
114    "mcpServers": {
115        "globalping": {
116            "url": "https://mcp.globalping.dev/mcp"
117        }
118    }
119}
120```
121Legacy SSE transport:
122```json
123{
124    "mcpServers": {
125        "globalping": {
126            "command": "npx",
127            "args": [
128                "mcp-remote",
129                "https://mcp.globalping.dev/sse"
130            ]
131        }
132    }
133}
134```
1355. Save and restart Cursor
136## Authentication
137 
138The Globalping MCP server supports two authentication methods:
139- **OAuth Authentication**: Automatically handled by the server for secure access
140- **API Token Authentication**: Manual token configuration via Authorization header
141 
142Both methods provide higher rate limits and priority access to the probe network.
143 
144### Using Globalping API Token
145 
146The server automatically detects when an API token is provided in the Authorization header and uses it for authentication instead of OAuth.
147 
148#### Getting Your API Token
149 
1501. Visit [dash.globalping.io](https://dash.globalping.io)
1512. Sign in to your account
1523. Navigate to Tokens to generate a new API token
153 
154#### Configuration with Authentication
155 
156Streamable HTTP transport:
157```json
158{
159    "mcpServers": {
160        "globalping": {
161            "url": "https://mcp.globalping.dev/mcp",
162            "headers": {
163                "Authorization": "Bearer YOUR_GLOBALPING_API_TOKEN"
164            }
165        }
166    }
167}
168```
169Legacy SSE transport:
170```json
171{
172    "mcpServers": {
173        "globalping": {
174            "command": "npx",
175            "args": [
176                "mcp-remote",
177                "https://mcp.globalping.dev/sse",
178                "--header",
179                "Authorization: Bearer YOUR_GLOBALPING_API_TOKEN"
180            ]
181        }
182    }
183}
184```
185 
186## Connecting AI Assistants
187 
188You can use our MCP server with any MCP-compatible AI assistant, including:
189 
190- Claude Desktop
191- Anthropic Assistants
192- Cursor
193- Windsurf
194- Any custom implementation of the MCP protocol
195 
196See your tool's MCP documentation for details on connecting clients to this server.
197 
198 
199## Available Tools
200 
201- `ping` - Perform a ping test to a target
202- `traceroute` - Perform a traceroute test to a target
203- `dns` - Perform a DNS lookup for a domain
204- `mtr` - Perform an MTR (My Traceroute) test to a target
205- `http` - Perform an HTTP request to a URL
206- `locations` - List all available Globalping probe locations
207- `limits` - Show your current rate limits for the Globalping API
208- `getMeasurement` - Retrieve a previously run measurement by ID
209- `compareLocations` - Guide on how to run comparison measurements
210- `help` - Show a help message with documentation on available tools
211 
212## Usage Examples
213 
214Once connected to an AI model through a compatible MCP client, you can interact with Globalping using natural language:
215 
216```
217Ping google.com from 3 locations in Europe
218```
219 
220```
221Run a traceroute to github.com from Japan and compare with traceroute from the US
222```
223 
224```
225Check the DNS resolution of example.com using Google DNS (8.8.8.8)
226```
227 
228```
229Is jsdelivr.com reachable from China? Test with both ping and HTTP
230```
231 
232```
233What's the average response time for cloudflare.com across different continents?
234```
235 
236 
237## Location Specification
238 
239Locations can be specified using the "magic" field, which supports various formats:
240 
241- Continent codes: "EU", "NA", "AS", etc.
242- Country codes: "US", "DE", "JP", etc.
243- City names: "London", "Tokyo", "New York", etc.
244- Network names: "Cloudflare", "Google", etc.
245- ASN numbers: "AS13335", "AS15169", etc.
246- Cloud provider regions: "aws-us-east-1", "gcp-us-central1", etc.
247 
248You can also combine these with a plus sign for more specific targeting: "London+UK", "Cloudflare+US", etc.
249 
250 
251## Development
252 
253The codebase is organized into modules:
254 
255- `src/index.ts` - Main entry point and MCP agent definition
256- `src/app.ts` - OAuth web routes
257- `src/api` - Globalping API client
258- `src/auth` - Authentication utilities
259- `src/config` - Configuration and constants
260- `src/lib` - Utility functions
261- `src/mcp` - MCP tool handlers
262- `src/types` - TypeScript type definitions
263- `src/ui` - HTML templates
264 
265 
266### Add Globalping credentials
267 
268Add Globalping OAuth credentials:
269 
270- `npx wrangler secret put GLOBALPING_CLIENT_ID`
271 
272### KV storage
273Used for `OAuthProvider` docs https://github.com/cloudflare/workers-oauth-provider
274- create a KV namespace and copy ID
275- binding for it must be `OAUTH_KV`
276- configure `kv_namespaces` in the `wrangler.jsonc` file
277