perfsonar-mcp

MCP (Model Context Protocol) server for perfSONAR - Query measurements, discover testpoints, and schedule network tests.

🚀 Features

Measurement Archive Queries

• Query historical measurements with filters
• Get throughput, latency, and packet loss data
• Access raw time-series data with summaries
• Discover available measurement types

Lookup Service Integration

• Find perfSONAR testpoints globally
• Search by location (city, country)
• Locate pScheduler services for testing

Test Scheduling (pScheduler)

• Schedule throughput tests (iperf3)
• Schedule latency tests (owping)
• Schedule RTT tests (ping)
• Monitor test status and retrieve results

📦 Installation

pip install -e .

For development with additional tools:

pip install -e '.[dev]'

⚙️ Configuration

Required environment variable:

export PERFSONAR_HOST=perfsonar.example.com

Optional:

export LOOKUP_SERVICE_URL=https://lookup.perfsonar.net/lookup
export PSCHEDULER_URL=https://perfsonar.example.com/pscheduler

🏃 Usage

Local (stdio transport)

Standard MCP stdio transport for local AI clients:

python -m perfsonar_mcp
# or
perfsonar-mcp

Web Access (SSE/HTTP transport)

FastMCP enables web-accessible MCP server via SSE (Server-Sent Events) or HTTP:

# SSE transport (recommended for web)
export PERFSONAR_HOST=perfsonar.example.com
fastmcp run src/perfsonar_mcp/fastmcp_server.py --transport sse --host 0.0.0.0 --port 8000

# HTTP transport (alternative)
fastmcp run src/perfsonar_mcp/fastmcp_server.py --transport http --host 0.0.0.0 --port 8000

# Or use the convenience command
perfsonar-mcp-web

The server will be accessible at:

• SSE: http://your-host:8000/sse
• HTTP: http://your-host:8000/mcp/

Docker

docker-compose up -d

Kubernetes

helm install perfsonar-mcp ./helm/perfsonar-mcp \
  --set config.perfsonarHost=perfsonar.example.com

🤖 Claude Desktop Integration

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "perfsonar": {
      "command": "python",
      "args": ["-m", "perfsonar_mcp"],
      "env": {
        "PERFSONAR_HOST": "your-perfsonar-host.example.com"
      }
    }
  }
}

For web-based access, use the SSE endpoint:

{
  "mcpServers": {
    "perfsonar-web": {
      "url": "http://your-server:8000/sse",
      "transport": "sse"
    }
  }
}

🔧 Available Tools (13)

Measurement Archive (6)

• query_measurements - Search measurements
• get_throughput - Throughput data
• get_latency - Latency data
• get_packet_loss - Packet loss data
• get_measurement_data - Raw time-series
• get_available_event_types - List types

Lookup Service (2)

• lookup_testpoints - Find testpoints
• find_pscheduler_services - Find pScheduler

pScheduler (5)

• schedule_throughput_test - Run throughput test
• schedule_latency_test - Run latency test
• schedule_rtt_test - Run RTT test
• get_test_status - Check status
• get_test_result - Get results

💡 Example Queries

Ask Claude:

"Find perfSONAR testpoints in Europe"

"Schedule a 30-second throughput test to host.example.com"

"Get hourly throughput averages between host1 and host2 for the last week"

🏗️ Architecture

Standard MCP (stdio)

AI Agent (Claude)
    ↓ MCP Protocol (stdio)
perfSONAR MCP Server (Python)
    ├── Measurement Archive Client
    ├── Lookup Service Client  
    └── pScheduler Client
        ↓
    perfSONAR Services

Web-Accessible MCP (SSE/HTTP)

Web Clients / AI Agents
    ↓ HTTP/SSE
FastMCP Web Server (uvicorn)
    ↓ MCP Protocol
perfSONAR MCP Server (Python)
    ├── Measurement Archive Client
    ├── Lookup Service Client  
    └── pScheduler Client
        ↓
    perfSONAR Services

Both transports expose the same tools and capabilities. The web transport enables:

• Remote access from any HTTP client
• Multiple concurrent connections
• Integration with web-based AI applications
• RESTful API-like access patterns

🛠️ Development

Logging

The server includes comprehensive logging for development and debugging. By default, logs are written to stderr at INFO level.

To enable DEBUG logging for more detailed output:

import logging
logging.basicConfig(level=logging.DEBUG)

Or set the log level via environment variable:

export PYTHONLOGLEVEL=DEBUG
python -m perfsonar_mcp

Log output includes:

• Server initialization and configuration
• API requests and responses
• Tool invocations with arguments
• Error details with stack traces

DevContainer

Open in VS Code → Reopen in Container

Local Development

# Install with dev dependencies
pip install -e '.[dev]'

# Format code
black src/perfsonar_mcp/

# Lint code
ruff check src/perfsonar_mcp/

# Type check
mypy src/perfsonar_mcp/

# Run tests
pytest tests/

📚 Documentation

• Deployment Guide
• Examples
• Contributing

🌐 Resources

• perfSONAR Docs
• MCP Protocol

📄 License

MIT