pvs2401/Apstra-MCP-Server

Apstra MCP Server

A Model Context Protocol (MCP) server for Apstra network management platform integration with Claude Desktop.

Features

• List Blueprints: Retrieve all blueprints from your Apstra system with detailed infrastructure information
• Blueprint Details: Get comprehensive information about specific blueprints
• Anomaly Detection: Check for network issues and anomalies in blueprints
• Device Management: List and manage devices in blueprints with detailed status
• Claude Desktop Integration: Seamless integration via stdio mode
• Modular Design: Clean, maintainable code structure
• Environment-based Configuration: Secure API token and URL management

Installation

1. Install dependencies:

   uv sync
   

2. Set up environment variables:

   export APSTRA_BASE_URL="https://your-apstra-server.com"
   export APSTRA_API_TOKEN="your-api-token-here"
   

Running the Server

The server runs in stdio mode for Claude Desktop integration:

uv run apstra

Claude Desktop Configuration

Add this to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apstra": {
      "command": "/Users/your-username/.local/bin/uv",
      "args": ["run", "--directory", "/path/to/your/Apstra", "apstra"],
      "env": {
        "APSTRA_BASE_URL": "https://your-apstra-server.com",
        "APSTRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Setup Steps:

1. Replace /path/to/your/Apstra with the actual path to this directory
2. Replace APSTRA_BASE_URL with your Apstra server URL
3. Replace APSTRA_API_TOKEN with your Apstra API authentication token
4. Restart Claude Desktop

Environment Variables

The following environment variables are required:

• APSTRA_BASE_URL - Your Apstra server URL (e.g., https://apstra.example.com)
• APSTRA_API_TOKEN - Your Apstra API authentication token

Architecture & Code Organization

Modular Design

The server follows a clean, modular architecture:

• apstra/server.py - Main MCP server with tool routing
• apstra/api_client.py - Pure API client (no formatting logic)
• apstra/tools/ - Individual tool modules with self-contained logic:
  • list_blueprints.py - Blueprint listing with formatting
  • get_blueprint_details.py - Blueprint details retrieval
  • check_blueprint_anomalies.py - Anomaly detection
  • list_blueprint_devices.py - Device listing with API schema compliance

Design Principles

• Separation of Concerns: API client only handles HTTP communication
• Tool Encapsulation: Each tool contains its own formatting and business logic
• Schema Compliance: Device listing follows official Apstra API schema
• Error Handling: Comprehensive error handling with graceful fallbacks
• Logging: Detailed logging for debugging and monitoring

list_blueprints

Returns all blueprints in the system with detailed infrastructure information in a formatted table.

Usage in Claude: "List all blueprints in my Apstra system"

Output includes:

• Blueprint Label
• Design Type
• Status
• Leaf Count
• Spine Count
• Remote Gateway Count
• Security Zone Count
• Virtual Network Count

get_blueprint_details

Get detailed information about a specific blueprint including configuration, deployment status, infrastructure details, and operational metrics.

Usage in Claude: "Get details for blueprint X" or "Show me detailed information about the datacenter blueprint"

check_blueprint_anomalies

Check for network anomalies, issues, and health problems in a specific blueprint. Identifies connectivity issues, configuration problems, device health concerns, and other operational anomalies.

Usage in Claude: "Check for anomalies in blueprint X" or "Are there any issues with the datacenter blueprint?"

list_blueprint_devices

List all system nodes (devices) in a specific blueprint with detailed information.

Usage in Claude: "List devices in blueprint X" or "Show me all devices in the datacenter blueprint"

API Endpoint Used: /api/blueprints/{blueprint_id}/nodes?node_type=system

Output includes:

• Device Label/Hostname
• System ID (serial number)
• Deploy Mode (deploy, undeploy, drain, etc.)
• Node Type
• Device Role (spine, leaf, server, etc.)
• Status
• Device counts by role and deploy mode
• Available device properties

Features:

• Uses correct Apstra API schema endpoints
• Handles different response formats gracefully
• Fallback to blueprint summary if device data unavailable
• Clear error handling and logging
• Detailed property analysis

Development

Testing

Test the server directly:

# Set environment variables
export APSTRA_BASE_URL="https://your-apstra-server.com"
export APSTRA_API_TOKEN="your-token"

# Run the server
uv run apstra

API Integration

This MCP server integrates with Apstra's REST API:

• Base URL: Configurable via APSTRA_BASE_URL
• Authentication: Bearer token via APSTRA_API_TOKEN
• Endpoints:
  • /api/blueprints - Blueprint listing and details
  • /api/blueprints/{id}/nodes?node_type=system - Device information
  • /api/blueprints/{id}/anomalies - Anomaly detection

Project Structure

apstra/
├── __init__.py                      # Package initialization
├── server.py                       # Main MCP server implementation
└── tools/                          # Tool modules
    ├── __init__.py                  # Tool exports
    ├── api_client.py               # Apstra API client
    ├── list_blueprints.py          # Blueprint listing
    ├── get_blueprint_details.py    # Blueprint details
    ├── check_blueprint_anomalies.py # Anomaly detection
    └── list_blueprint_devices.py   # Device management

Troubleshooting

1. Configuration errors: Ensure APSTRA_BASE_URL and APSTRA_API_TOKEN are set correctly
2. Connection issues: Verify your Apstra server is accessible and the API token is valid
3. MCP server not starting: Check the Claude Desktop logs for detailed error messages
4. Tool execution errors: Check that the Apstra API endpoints are responding correctly