Skip to main content
Glama
MCP Simple Example

MCP Simple Example

by rmschn

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

  1. mcp_server.py: The main MCP server implementation

    • Implements the MCP protocol over stdio

    • Defines two tools: network-ping, network-traceroute

    • Handles tool execution and response formatting

  2. 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

network-ping

Test host reachability and latency

host, count

network-traceroute

Trace network path to host

host, max_hops, timeout

Related MCP server: netops-mcp

Prerequisites

System Requirements

Required System Tools

The server uses the following system commands (must be installed on your system):

Command

Purpose

Install (Debian/Ubuntu)

Install (macOS)

ping

ICMP echo requests

apt install iputils-ping

Built-in

traceroute

Network path tracing

apt install traceroute

Built-in

Ollama Setup (for AI Integration)

To use with an AI assistant:

  1. Install Ollama: https://ollama.ai

  2. Pull the model: ollama pull llama3.1:8b

  3. Start Ollama: ollama serve

Installation

Step 1: Clone or Navigate to the Project

cd /path/to/simple_mcp_example

Step 2: Install Dependencies with uv

# Install all dependencies using uv
uv sync

# Or install the MCP package directly
uv add mcp python-dotenv

Step 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.py

Interactive Test Client

The easiest way to test the server:

# Run the interactive test client
uv run python mcp_client.py

You can then type commands like:

> ping google.com
> traceroute cloudflare.com
> quit

Configuration

Environment Variables

The server doesn't require environment variables, but you can add them to pyproject.toml if needed:

[tool.mcp-server.env]
# DEBUG=true

Customizing 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

host

string

Yes

-

Hostname or IP address

count

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.5ms

Tool: network-traceroute

Trace the network path to a destination host.

Parameters:

Name

Type

Required

Default

Description

host

string

Yes

-

Hostname or IP address

max_hops

integer

No

30

Maximum hops to trace

timeout

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:

  1. Server is taking too long to start

  2. Network issues between client and server

  3. 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 tools
network-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 ICMP

Inputs: 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

    A4.2/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    Both tools follow the same network-<command> naming pattern, making the set predictable and easy to navigate. The consistency holds across both tools.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Network diagnostics — ping, traceroute, DNS lookup, port scanning, and connectivity testing via MCP.
      14
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Provides network operations tools such as ping, traceroute, DNS queries, and nmap scans via MCP, enabling network diagnostics and monitoring through natural language.
      30
      16
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that exposes live network monitoring data as Resources and diagnostic capabilities as Tools, letting AI assistants query network health conversationally.
      6
      MIT