Skip to content

Claude Code Integration

Jump to bottom
Herve Hildenbrand edited this page Feb 3, 2026 · 7 revisions

Claude Code Integration

BGP Explorer can be used as an MCP (Model Context Protocol) server with Claude Code, allowing you to use BGP investigation tools with your Claude Code subscription (Pro/Max) instead of requiring a separate Anthropic API key.

Overview

┌─────────────────────────────────────────────────────────────┐
│                     Claude Code (CLI)                        │
│                                                              │
│  AI Processing: Uses YOUR Claude Code subscription          │
│  (Pro/Max credits - NOT a separate API key)                 │
│                                                              │
└───────────────────────────┬──────────────────────────────────┘
                            │ MCP Protocol (stdio)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  bgp-explorer MCP Server                     │
│                                                              │
│  NO AI here - just data fetching tools:                     │
│  - RIPE Stat (free API)                                     │
│  - Monocle CLI (free)                                       │
│  - Globalping (free tier)                                   │
│  - PeeringDB cache (free)                                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Key point: The MCP server contains zero AI code. All AI reasoning happens in Claude Code using your subscription credits.

Setup

1. Install BGP Explorer

git clone https://github.com/hervehildenbrand/bgp-explorer.git
cd bgp-explorer
uv sync
uv run bgp-explorer install-deps  # Installs monocle and bgp-radar

2. Add to Claude Code

Important: You must use the full path to the bgp-explorer directory because the bgp-explorer command is not globally installed.

# Add bgp-explorer as an MCP server (replace with YOUR actual path)
claude mcp add bgp-explorer -- uv run --directory /path/to/bgp-explorer bgp-explorer mcp

# Example paths:
# macOS/Linux:
claude mcp add bgp-explorer -- uv run --directory ~/Code/bgp-explorer bgp-explorer mcp

# Or with absolute path:
claude mcp add bgp-explorer -- uv run --directory /Users/yourname/Code/bgp-explorer bgp-explorer mcp

This tells Claude Code to:

  1. Change to the bgp-explorer directory
  2. Run uv run bgp-explorer mcp which starts the MCP server

3. Verify Installation

# Check the MCP server is registered
claude mcp list

# Should show:
# bgp-explorer: uv run --directory /your/path/bgp-explorer bgp-explorer mcp - ✓ Connected

4. Use Claude Code

claude

Now you can ask BGP-related questions and Claude Code will automatically use the bgp-explorer tools:

> Search for Cloudflare's ASNs
> How many peers does AS13335 have?
> Check if 8.8.8.0/24 is being hijacked
> Ping 1.1.1.1 from Asia
> What IXPs is Google present at?

Available Tools (24)

The MCP server exposes 24 BGP investigation tools with security-first methodology (proactive RPKI checks) and IPv4/IPv6 awareness (separate reporting by address family):

RIPE Stat Tools (Core Routing Data)

Tool Description
search_asn Search for ASNs by organization name
lookup_prefix Get origin ASN, AS paths, visibility for a prefix
get_asn_announcements List all prefixes announced by an ASN
get_routing_history Historical routing data for a resource
get_rpki_status RPKI validation (valid/invalid/not-found)
analyze_as_path Path diversity, transit ASNs, prepending detection
get_asn_details Detailed ASN analysis
check_prefix_anomalies On-demand hijack detection (MOAS, RPKI, origin changes)

Monocle Tools (AS Relationships)

Tool Description
get_as_peers Get all peers for an AS
get_as_upstreams Get upstream transit providers
get_as_downstreams Get downstream customers
check_as_relationship Check relationship between two ASes
get_as_connectivity_summary Overview of AS's network position

Globalping Tools (Network Probing)

Tool Description
ping_from_global Ping from worldwide vantage points
traceroute_from_global Traceroute from multiple locations

PeeringDB Tools (Network Info)

Tool Description
get_ixps_for_asn Get IXP presence for an ASN
get_network_contacts Get NOC/abuse contacts

Resilience Tools

Tool Description
assess_network_resilience Score network resilience (1-10) with transit, peering, IXP analysis

Example Queries

Finding an ASN

> Search for Google's ASNs

Claude will use search_asn to find AS15169 and related ASNs.

Investigating a Prefix

> Is 203.0.113.0/24 being hijacked?

Claude will use check_prefix_anomalies to check for:
- Multiple Origin AS (MOAS)
- RPKI validation status
- Recent origin changes
- Visibility anomalies

Network Connectivity

> How well connected is Cloudflare?

Claude will use get_as_connectivity_summary to show:
- Total neighbors (upstreams, peers, downstreams)
- Top providers and customers
- Visibility across BGP peers

Global Reachability

> Ping 8.8.8.8 from Europe and show latency

Claude will use ping_from_global with location=['Europe'] to run
measurements from European vantage points.

Managing the MCP Server

List MCP Servers

claude mcp list

Remove bgp-explorer

claude mcp remove bgp-explorer

Check Server Status

When in Claude Code, type /mcp to see connected MCP servers and their status.

Troubleshooting

"Failed to reconnect to bgp-explorer" or "command not found"

This is the most common issue. It means the MCP server command path is wrong.

Cause: The bgp-explorer command is NOT globally installed. It only works via uv run.

Fix: Re-add the MCP server with the correct full path:

# First remove the broken configuration
claude mcp remove bgp-explorer

# Re-add with correct command (use YOUR actual path)
claude mcp add bgp-explorer -- uv run --directory /path/to/bgp-explorer bgp-explorer mcp

# Verify it works
claude mcp list

Common mistakes:

  • ❌ bgp-explorer mcp - Won't work (not globally installed)
  • ❌ uv run bgp-explorer mcp - Won't work (needs directory context)
  • ✅ uv run --directory /path/to/bgp-explorer bgp-explorer mcp - Correct!

"Monocle is not configured"

The monocle binary isn't installed or not in PATH:

# Navigate to bgp-explorer directory first
cd /path/to/bgp-explorer

# Install monocle
uv run bgp-explorer install-deps

# Or manually:
cargo install monocle

Tools Not Appearing

  1. Check the MCP server is added and connected:

    claude mcp list
# Should show: bgp-explorer: ... - ✓ Connected

  2. If it shows "Not connected" or error, re-add with correct path (see above)

  3. Restart Claude Code after fixing the configuration

  4. Test the MCP server manually:

    cd /path/to/bgp-explorer
uv run bgp-explorer mcp --help

Slow Responses

Some queries (especially AS connectivity) can take a few seconds because they:

  • Query external APIs (RIPE Stat, Globalping)
  • Run the monocle CLI
  • Process large datasets

This is normal for BGP data analysis.

Comparison: MCP Server vs Standalone Mode

Feature MCP Server (bgp-explorer mcp) Standalone (bgp-explorer chat)
AI Processing Claude Code subscription Anthropic API key
Tools Available 18 (no real-time monitoring) 24 (includes monitoring)
Use Case Quick queries in Claude Code Dedicated BGP investigation
API Costs Included in Claude Code sub Per-token API charges

Note: The MCP server does not include real-time monitoring tools (start_monitoring, stop_monitoring, get_anomalies) because those require a long-running bgp-radar process which doesn't fit the MCP request-response model. Use standalone mode for real-time monitoring.

Clone this wiki locally