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

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