MCP Simple Example
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Simple Example Can you ping google.com?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Simple Example
A Model Context Protocol (MCP) server that provides network diagnostic tools (ping, traceroute) as AI-accessible tools. Works with any MCP-compatible client
Overview
This project creates an MCP server that exposes network diagnostic commands as tools that can be called by any MCP-compatible AI assistant. The AI assistant (powered by Ollama with llama3.1:8b) can use these tools to diagnose network issues, check host connectivity, trace network paths
What is MCP?
The Model Context Protocol (MCP) is an open standard developed by Anthropic for connecting AI assistants to external tools and data sources. Instead of hardcoding tool implementations in every AI client, MCP allows:
Standardized Tool Interface: Tools are defined once and work with any MCP client
Secure Execution: Tools run in isolation, reducing security risks
Easy Integration: MCP clients can discover and use tools dynamically
Language Agnostic: Servers can be written in any language (Python, TypeScript, Go, etc.)
Components
mcp_server.py: The main MCP server implementation
Implements the MCP protocol over stdio
Defines two tools:
network-ping,network-tracerouteHandles tool execution and response formatting
mcp_client.py: Interactive CLI test client
Allows manual testing of all tools
Useful for debugging without an AI assistant
Tool Definitions
Tool | Purpose | Key Parameters |
| Test host reachability and latency |
|
| Trace network path to host |
|
Related MCP server: netops-mcp
Prerequisites
System Requirements
Python: 3.10 or higher
uv: Package manager (install from https://github.com/astral-sh/uv)
Required System Tools
The server uses the following system commands (must be installed on your system):
Command | Purpose | Install (Debian/Ubuntu) | Install (macOS) |
| ICMP echo requests |
| Built-in |
| Network path tracing |
| Built-in |
Ollama Setup (for AI Integration)
To use with an AI assistant:
Install Ollama: https://ollama.ai
Pull the model:
ollama pull llama3.1:8bStart Ollama:
ollama serve
Installation
Step 1: Clone or Navigate to the Project
cd /path/to/simple_mcp_exampleStep 2: Install Dependencies with uv
# Install all dependencies using uv
uv sync
# Or install the MCP package directly
uv add mcp python-dotenvStep 3: Verify Installation
# Check that uv created the virtual environment
ls -la .venv
# Verify Python can see the packages
uv run python -c "import mcp; print('MCP installed')"Step 4: Install System Tools (if needed)
# Debian/Ubuntu
sudo apt update
sudo apt install iputils-ping traceroute
Usage
Direct Server Execution
Start the server directly (outputs to stderr):
uv run python mcp_server.pyInteractive Test Client
The easiest way to test the server:
# Run the interactive test client
uv run python mcp_client.pyYou can then type commands like:
> ping google.com
> traceroute cloudflare.com
> quitConfiguration
Environment Variables
The server doesn't require environment variables, but you can add them to pyproject.toml if needed:
[tool.mcp-server.env]
# DEBUG=trueCustomizing Tool Behavior
Edit mcp_server.py to customize:
Add New Tools
Add new Tool definitions and handlers in mcp_server.py.
API Reference
Tool: network-ping
Test connectivity and measure latency to a host.
Parameters:
Name | Type | Required | Default | Description |
| string | Yes | - | Hostname or IP address |
| integer | No | 4 | Number of packets |
Example Request:
{
"method": "tools/call",
"params": {
"name": "network-ping",
"arguments": {
"host": "google.com",
"count": 4
}
}
}Example Response:
# Ping Results for google.com
## Command Output
PING google.com (142.250.80.46): 56 data bytes
64 bytes from 142.250.80.46: icmp_seq=0 ttl=117 time=10.123 ms
64 bytes from 142.250.80.46: icmp_seq=1 ttl=117 time=10.456 ms
...
## Summary
ā 0% packet loss - Host is fully reachable
Latency (RTT): min=10.1ms, avg=10.3ms, max=10.5msTool: network-traceroute
Trace the network path to a destination host.
Parameters:
Name | Type | Required | Default | Description |
| string | Yes | - | Hostname or IP address |
| integer | No | 30 | Maximum hops to trace |
| integer | No | 5 | Seconds to wait per hop |
Example Request:
{
"method": "tools/call",
"params": {
"name": "network-traceroute",
"arguments": {
"host": "cloudflare.com",
"max_hops": 15
}
}
}Troubleshooting
"ping command not found"
Solution: Install ping utilities
# Debian/Ubuntu
sudo apt install iputils-ping
# macOS
# ping is built-in"Server timed out" or "Connection failed"
Possible causes:
Server is taking too long to start
Network issues between client and server
Host is unreachable
Solutions:
# Check server starts correctly
uv run python mcp_server.py
License
MIT License - Feel free to use, modify, and distribute.
Available Tools
2 toolsnetwork-pingA
Send ICMP echo requests to a host to test connectivity and measure latency.
USE CASES:
- Check if a host is reachable over the network
- Measure round-trip time (latency) to a host
- Diagnose network connectivity issues
- Verify if a firewall is blocking ICMP traffic
WHAT IT DOES:
- Sends multiple ICMP echo request packets to the target host
- Waits for echo response packets
- Reports packet loss percentage and response times
PARAMETERS:
- host: Required. The hostname or IP address to ping (e.g., 'google.com', '8.8.8.8')
- count: Optional. Number of ping packets to send (default: 4)
OUTPUT:
- Packet loss statistics
- Min/Avg/Max response times
- Will show '100% packet loss' if host is unreachable or blocking ICMPInputs: host (required), count.
network-tracerouteA
Trace the route that packets take to reach a destination host.
USE CASES:
- Identify network path between source and destination
- Diagnose where network latency is occurring
- Find broken or slow network hops
- Understand network topology for debugging
WHAT IT DOES:
- Sends packets with increasing TTL (Time To Live) values
- Each router along the path decrements TTL and returns its IP
- Shows all intermediate hops between your machine and target
PARAMETERS:
- host: Required. The hostname or IP address to trace (e.g., 'cloudflare.com')
- max_hops: Optional. Maximum number of hops to trace (default: 30)
- timeout: Optional. Seconds to wait for each hop response (default: 5)
OUTPUT:
- List of all hops (routers) along the path
- IP address of each hop
- Round-trip time for each hop
- Shows '* * *' for hops that don't respond
NOTE: On Windows, this command is called 'tracert' instead of 'traceroute'Inputs: host (required), timeout, max_hops.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: ping tests reachability and latency, while traceroute maps the network path. There is no realistic confusion between them.
Both tools follow the same network-<command> naming pattern, making the set predictable and easy to navigate. The consistency holds across both tools.
With only two tools, the server feels thin, but the pair of ping and traceroute forms a natural, coherent unit for basic network diagnostics. It is slightly under the typical well-scoped range but not unreasonable for a simple example server.
For basic network troubleshooting, ping and traceroute cover the two most common diagnostic needs: connectivity/latency and route/path analysis. A DNS lookup or port check would be a minor enhancement, but the current surface is not severely incomplete for the implied scope.
Maintenance
Related MCP Connectors
Network, domain and website diagnostics for AI clients via MCP.
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
MCP tools for AI agents: render URLs to image/PDF, check link health, convert HTML/CSV/JSON.
MCP diagnostics that help AI agents find safe next steps for HTTP, API, and MCP failures.
Related MCP Servers
- AlicenseAqualityCmaintenanceNetwork diagnostics ā ping, traceroute, DNS lookup, port scanning, and connectivity testing via MCP.14MIT
- AlicenseCqualityCmaintenanceProvides network operations tools such as ping, traceroute, DNS queries, and nmap scans via MCP, enabling network diagnostics and monitoring through natural language.3016MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform real network diagnostics on the local machine, including ping, traceroute, DNS lookups, TLS checks, and more.MIT
- AlicenseAqualityDmaintenanceAn MCP server that exposes live network monitoring data as Resources and diagnostic capabilities as Tools, letting AI assistants query network health conversationally.6MIT