mcp-dnac

RobertBergman/mcp-dnac

3.2

If you are the rightful owner of mcp-dnac and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Cisco DNA Center (DNAC) Wireless MCP Server provides intelligent wireless client management for Cisco DNA Center, enabling AI assistants to interact with your infrastructure with advanced filtering and real-time data.

Tools
8
Resources
0
Prompts
0

Cisco DNA Center (DNAC) Wireless MCP Server

MCP server providing intelligent wireless client management for Cisco DNA Center. This server exposes powerful DNAC wireless client queries through the Model Context Protocol (MCP), enabling AI assistants like Claude to interact with your DNA Center infrastructure with advanced filtering and real-time data.

Features

Client Management

  • 🔍 Smart Filtering: Filter wireless clients by building name, AP name, or both
  • ⏱️ Time-Based Queries: Get only active clients (last 15 minutes) or historical data
  • 👤 Client Details: Deep-dive into individual client health and connection metrics
  • ❤️ Health Monitoring: Track client health statistics and identify unhealthy clients

Infrastructure Monitoring

  • 📡 AP Inventory: Complete Access Point inventory with pagination (500+ APs supported)
  • 🏢 Site Hierarchy: Organized view of your network topology (root/buildings/floors)
  • 📊 Model Distribution: Automatic AP model categorization and statistics
  • 📍 Location Intelligence: Automatic site/building name to UUID resolution

Issue & Compliance

  • ⚠️ Issue Tracking: Get active wireless issues with root cause analysis and suggested fixes
  • ✅ Compliance Status: Monitor configuration drift and image compliance
  • 🎯 Priority Filtering: Filter issues by priority (P1-P4) and status (ACTIVE/RESOLVED)

Application & Performance

  • 📱 App Health: Application performance monitoring and health metrics
  • 🔒 Secure Authentication: Token-based authentication with auto-refresh on 401
  • ⚡ Async Operations: Built with httpx for efficient async API calls
  • 🚀 FastMCP Framework: Simplified tool creation with FastMCP
  • 📄 Pagination Support: Handle large datasets with limit/offset pagination

Production Tested

  • ✅ 949 Access Points
  • ✅ 3,397 Wireless Clients
  • ✅ 186 Configured Sites
  • ✅ Live DNA Center Environment

Installation

Prerequisites

  • Python 3.10 or higher
  • Access to Cisco DNA Center with API credentials
  • Claude Desktop or another MCP client

Install from Source

# Clone the repository
git clone https://github.com/robertbergman/dnac-mcp.git
cd dnac-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

Install for Development

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

# Run tests
pytest

# Format code
black src tests

# Lint code
ruff check src tests

Configuration

The server requires three environment variables for DNA Center authentication:

export DNAC_BASE_URL="https://dnac.example.com"
export DNAC_USERNAME="admin"
export DNAC_PASSWORD="your-password"

On Windows:

$env:DNAC_BASE_URL="https://dnac.example.com"
$env:DNAC_USERNAME="admin"
$env:DNAC_PASSWORD="your-password"

Note: The server automatically handles HTTPS URLs and accepts self-signed certificates (SSL verification is disabled by default for DNAC deployments).

Claude Desktop Configuration

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "dnac-wireless": {
      "command": "python",
      "args": ["-m", "dnac_mcp.server"],
      "env": {
        "DNAC_BASE_URL": "https://dnac.example.com",
        "DNAC_USERNAME": "admin",
        "DNAC_PASSWORD": "your-password"
      }
    }
  }
}

Or use the installed script:

{
  "mcpServers": {
    "dnac-wireless": {
      "command": "dnac-mcp",
      "env": {
        "DNAC_BASE_URL": "https://dnac.example.com",
        "DNAC_USERNAME": "admin",
        "DNAC_PASSWORD": "your-password"
      }
    }
  }
}

After updating the config, restart Claude Desktop.

Usage

Available Tools

The MCP server provides 8 comprehensive tools for managing and monitoring your Cisco DNA Center wireless infrastructure:

1. get_filtered_wireless_clients

Get a list of wireless clients with powerful filtering options including building name, AP name, time-based filtering, and pagination.

Parameters:

  • building_name (optional): Partial name of the building (e.g., "Building 24")

    • The tool automatically resolves building names to site IDs
    • Case-insensitive partial matching supported

  • ap_name (optional): Name of a specific Access Point

    • The tool automatically resolves AP names to MAC addresses
    • Case-insensitive matching with post-filtering for accuracy

  • limit (optional): Maximum number of results to return (default: 100)

    • Controls pagination size
    • If limit is reached, response includes a note to fetch the next page

  • offset (optional): Starting index for pagination (default: 1)

    • Use with limit for pagination
    • Example: offset=101 gets the second page when limit=100

  • only_active (optional): Filter for active clients only (default: true)

    • When true: Returns only clients seen in the last 15 minutes
    • When false: Returns all clients including historical connections
    • Prevents returning stale data from hours/days ago

Returns:

JSON string containing:

  • total_returned: Number of clients in this response
  • limit_used: The limit parameter used
  • offset_used: The offset parameter used
  • clients: Array of client objects with:
    • MAC: Client MAC address
    • IP: Client IP address
    • SSID: Connected wireless network name
    • AP Name: Connected Access Point name
    • Health: Health score (0-10)
    • Site: Site hierarchy location
    • Last Updated: Timestamp of last client update
  • note (conditional): Pagination hint when limit is reached

Example Prompts for Claude:

"Show me all active wireless clients in Building 24"

"List wireless clients connected to AP-Floor2-East"

"Find all clients in Building 24 connected to AP-Floor2-East"

"Show me the first 50 wireless clients, only those active right now"

"Get the next page of wireless clients (offset 101)"

"Show me all wireless clients including historical connections"

"List clients on AP-Lobby with health scores"
2. get_site_hierarchy

Get all configured sites organized by hierarchy (root/area, buildings, floors).

Parameters: None

Returns: Structured view of the site hierarchy including:

  • Total site count by type (root, buildings, floors)
  • Site IDs for use in other queries
  • Organized categorization of your network topology

Example Prompts:

"Show me the site hierarchy"
"List all buildings in DNA Center"
"What sites are configured?"
3. get_ap_inventory

Get wireless Access Point inventory with detailed information and pagination support.

Parameters:

  • limit (optional): Number of APs to retrieve, max 500 per page (default: 500)
  • offset (optional): Starting offset for pagination, 1-based (default: 1)

Returns: AP details including:

  • Hostname, model, IP address, MAC address
  • Software version and serial number
  • Location information
  • Model distribution statistics

Example Prompts:

"Show me all access points"
"List the first 100 APs"
"Get AP inventory with model distribution"
"Show me the next page of APs (offset 501)"
4. get_wireless_issues

Get active wireless network issues with root cause analysis and suggested fixes.

Parameters:

  • priority (optional): Issue priority - p1, p2, p3, p4 (default: "p1" for critical)
  • status (optional): Issue status - ACTIVE, RESOLVED (default: "ACTIVE")

Returns: Issue details including:

  • Issue ID, name, priority, and category
  • Affected device type
  • Suggested remediation actions
  • Occurrence count

Example Prompts:

"Show me critical wireless issues"
"List all active P1 and P2 issues"
"What wireless problems do we have?"
"Show resolved issues"
5. get_unhealthy_clients

Get wireless client health statistics and identify unhealthy clients.

Parameters:

  • health_threshold (optional): Health score threshold 0-100 (default: 7)

Returns: Client health statistics including:

  • Total client count and unhealthy client count
  • Percentage of unhealthy clients
  • Health categories breakdown (ALL, WIRED, WIRELESS)
  • Individual health scores per category

Example Prompts:

"Show me unhealthy wireless clients"
"Check client health status"
"How many clients have poor health?"
"List clients with health score below 5"
6. get_client_detail

Get comprehensive health and connection information for a specific wireless client.

Parameters:

  • mac_address (required): Client MAC address (format: xx:xx:xx:xx:xx:xx or xx-xx-xx-xx-xx-xx)

Returns: Detailed client information including:

  • Health score and IP/hostname
  • SSID, frequency, channel
  • Onboarding status and time
  • Connected AP name
  • Connection status, RSSI, SNR
  • Site hierarchy and VLAN

Example Prompts:

"Show me details for client 00:11:22:33:44:55"
"Get client detail for MAC aa:bb:cc:dd:ee:ff"
"Check onboarding status for client xx:xx:xx:xx:xx:xx"
7. get_app_health

Get application health statistics and performance metrics.

Parameters:

  • site_id (optional): Site ID to filter applications by location

Returns: Application health including:

  • Total application count
  • Health scores per application
  • Business relevance classification
  • Traffic class and usage statistics

Example Prompts:

"Show me application health"
"List application performance metrics"
"Get app health for site xyz-123"
"What applications are monitored?"
8. get_compliance_status

Check device compliance status for configuration drift and image compliance.

Parameters:

  • device_uuid (optional): Device UUID to check specific device
  • compliance_type (optional): Filter by status - NON_COMPLIANT, COMPLIANT (default: "NON_COMPLIANT")

Returns: Compliance details including:

  • Device UUID and hostname
  • Compliance status and type
  • Last update time
  • Mismatch details for non-compliant devices

Example Prompts:

"Show me non-compliant devices"
"Check compliance status"
"List devices with configuration drift"
"Show compliant devices"

Smart Features:

  1. Automatic Name Resolution: You don't need to know UUIDs or MAC addresses

    • Building names are automatically resolved to site IDs
    • AP names are automatically resolved to MAC addresses

  2. Time Filtering: By default, only active clients (last 15 minutes) are returned

    • Prevents confusion from stale data
    • Can be disabled with only_active=false for historical queries

  3. Post-Filtering: Even when API filtering is unreliable across DNAC versions

    • Python-based post-filtering ensures accuracy
    • Particularly useful for AP name filtering

  4. Pagination Awareness: The tool tells Claude when more data is available

    • Response includes a note field when limit is reached
    • Claude can automatically request the next page

Example Workflows

Find Clients in a Specific Location

User: "Show me all wireless clients in Building 24"

Claude calls: get_filtered_wireless_clients(building_name="Building 24")

Result: All active clients in Building 24 with full details

Find Clients on a Specific AP

User: "Which clients are connected to AP-Conference-Room?"

Claude calls: get_filtered_wireless_clients(ap_name="AP-Conference-Room")

Result: All clients connected to that specific AP

Combined Filtering

User: "Show me clients in Building 24 that are on AP-Floor2-East"

Claude calls: get_filtered_wireless_clients(
    building_name="Building 24",
    ap_name="AP-Floor2-East"
)

Result: Only clients matching both criteria

Pagination for Large Datasets

User: "Show me all wireless clients"

Claude calls: get_filtered_wireless_clients(limit=100, offset=1)
Response: 100 clients with note: "Limit reached. Ask for the next page."

Claude automatically calls: get_filtered_wireless_clients(limit=100, offset=101)
Result: Next 100 clients

Historical Data Query

User: "Show me all clients including those that disconnected earlier today"

Claude calls: get_filtered_wireless_clients(only_active=false)

Result: All clients including historical connections

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/dnac_mcp --cov-report=html

# Run specific test file
pytest tests/test_server.py

# Run with verbose output
pytest -v

Code Quality

# Format code
black src tests

# Lint code
ruff check src tests

# Type checking
mypy src

Project Structure

dnac-mcp/
├── src/
│   └── dnac_mcp/
│       ├── __init__.py           # Package initialization
│       └── server.py             # FastMCP server implementation
├── tests/
│   └── __init__.py
├── scripts/
│   └── verify_setup.py           # Setup verification script
├── pyproject.toml                # Project configuration
└── README.md                     # This file

Troubleshooting

Connection Issues

Problem: Cannot connect to DNAC

Solution:

  • Verify DNAC_BASE_URL is correct (can be with or without https://)
  • Check DNAC_USERNAME and DNAC_PASSWORD credentials
  • Ensure network connectivity to DNAC server
  • Check firewall rules allow access to DNAC API

Authentication Errors

Problem: Authentication fails with 401 error

Solution:

  • Verify credentials are correct
  • Check user has API access permissions in DNAC
  • Ensure user account is not locked
  • The server automatically handles token refresh on 401 errors

SSL Certificate Errors

Problem: SSL verification fails

Solution: The server is pre-configured to accept self-signed certificates (common in DNAC deployments). SSL verification is disabled by default via verify=False in the httpx client.

No Data Returned

Problem: Queries return "No clients found matching filters"

Solution:

  • Verify DNAC has wireless clients connected
  • Check if only_active=true is filtering out clients (try only_active=false)
  • Verify building_name or ap_name are spelled correctly
  • Try without filters first to confirm clients exist

Site/Building Not Found

Problem: "Error: Could not find a site matching 'Building XX'"

Solution:

  • Check the exact building name in DNAC
  • Try a partial name (e.g., "Building" instead of "Building 24 - Floor 2")
  • Site names are case-insensitive
  • Verify the site exists in DNAC's site hierarchy

AP Not Found

Problem: "Error: Could not find Access Point named 'AP-XXX'"

Solution:

  • Check the exact AP hostname in DNAC
  • Verify the AP is managed by DNAC
  • Try using the full hostname as it appears in DNAC

Pagination Issues

Problem: Not getting all results

Solution:

  • Look for "note": "Limit reached..." in the response
  • Increment offset by limit value (e.g., if limit=100, use offset=101, 201, 301...)
  • Continue until total_returned < limit_used

API Reference

DNACClient Class

The DNACClient class handles authentication and API requests:

class DNACClient:
    async def _authenticate(self) -> None:
        """Authenticate and retrieve X-Auth-Token"""

    async def get(self, endpoint: str, params: dict = None) -> Dict[str, Any]:
        """Make authenticated GET request with auto-reauth on 401"""

Helper Functions

async def resolve_site_id(site_name_pattern: str) -> Optional[str]:
    """Finds a siteId based on a name search (case-insensitive)"""

async def resolve_ap_mac(ap_name: str) -> Optional[str]:
    """Finds an AP's MAC address by its hostname"""

Tool Function

@mcp.tool()
async def get_filtered_wireless_clients(
    building_name: Optional[str] = None,
    ap_name: Optional[str] = None,
    limit: int = 100,
    offset: int = 1,
    only_active: bool = True
) -> str:
    """Get filtered list of wireless clients with pagination"""

DNAC API Endpoints Used

This server uses the following DNAC Intent API endpoints:

Authentication

  • POST /dna/system/api/v1/auth/token - Get authentication token
    • Uses Basic Auth (username/password)
    • Returns X-Auth-Token for API requests
    • Token automatically refreshed on 401 errors

Client Management

  • GET /dna/intent/api/v1/client-detail - Get detailed client information

    • Parameters: category, limit, offset, startTime, endTime, siteId, macAddress, timestamp
    • Used by: get_filtered_wireless_clients, get_client_detail

  • GET /dna/intent/api/v1/client-health - Get client health statistics

    • Parameters: timestamp
    • Used by: get_unhealthy_clients

Infrastructure

  • GET /dna/intent/api/v1/site - Get all sites and hierarchy

    • Used by: get_site_hierarchy, resolve_site_id helper

  • GET /dna/intent/api/v1/network-device - Get network devices (APs, WLCs)

    • Parameters: family, hostname, offset, limit
    • Used by: get_ap_inventory, resolve_ap_mac helper

Monitoring & Issues

  • GET /dna/intent/api/v1/issues - Get network issues with root cause

    • Parameters: priority, issueStatus
    • Used by: get_wireless_issues

  • GET /dna/intent/api/v1/application-health - Get application health metrics

    • Parameters: siteId (optional)
    • Used by: get_app_health

Compliance

  • GET /dna/intent/api/v1/compliance/detail - Get device compliance status
    • Parameters: complianceStatus, deviceUuid
    • Used by: get_compliance_status

Key Implementation Details

Time-Based Filtering (only_active)

When only_active=true (default), the tool:

  • Calculates current time in milliseconds
  • Subtracts 15 minutes (900,000 ms)
  • Sends startTime and endTime parameters to API
  • Ensures only clients seen in last 15 minutes are returned

This prevents returning clients who disconnected hours or days ago.

Building Name Resolution

The tool:

  1. Fetches all sites from /dna/intent/api/v1/site
  2. Performs case-insensitive partial match on siteNameHierarchy
  3. Returns the id (UUID) of the first match
  4. Uses this UUID in the siteId parameter of client query

AP Name Resolution

The tool:

  1. Queries /dna/intent/api/v1/network-device with hostname parameter
  2. Extracts the macAddress from the first result
  3. Applies post-filtering on results to ensure accuracy (some DNAC versions don't support AP filtering in the API)

Post-Filtering for AP Names

Even after querying with filters, the tool:

  • Iterates through all returned clients
  • Checks if connectedDevice[0].name contains the AP name (case-insensitive)
  • Skips clients that don't match
  • Ensures accuracy across different DNAC API versions

Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Write tests for new functionality
  4. Format code: black src tests
  5. Lint code: ruff check src tests
  6. Run tests: pytest
  7. Commit changes: git commit -am 'Add feature'
  8. Push to branch: git push origin feature-name
  9. Submit a Pull Request

License

MIT License - see file for details.

Support

Acknowledgments

Roadmap

Completed ✅

  • Add health score filtering (get_unhealthy_clients)
  • Add network device queries (get_ap_inventory)
  • Integration with DNAC Assurance APIs (issues, health, compliance)
  • Site hierarchy management
  • Client detail queries with MAC address
  • Application health monitoring
  • Compliance status checking
  • Wireless issue tracking with root cause

Planned 🚧

  • Add SSID-based filtering to client queries
  • Add IP address exact match filtering
  • Support for wired clients
  • Implement client troubleshooting tools (trace, path analysis)
  • Client session history and trends
  • Rogue AP detection (version-dependent endpoint)
  • Export capabilities (CSV/JSON)
  • Network topology visualization data
  • WLAN configuration queries
  • RF analytics and channel utilization

Changelog

v2.0.0 (2025-01-18)

  • Major expansion: 8 comprehensive tools (previously 1)

    • get_filtered_wireless_clients - Enhanced client filtering with building/AP filters
    • get_site_hierarchy - Site organization and topology
    • get_ap_inventory - Access Point inventory with pagination
    • get_wireless_issues - Issue tracking with root cause analysis
    • get_unhealthy_clients - Client health monitoring and statistics
    • get_client_detail - Individual client deep-dive (MAC-based)
    • get_app_health - Application performance monitoring
    • get_compliance_status - Configuration and image compliance checking

  • Enhanced infrastructure monitoring

    • AP inventory with model distribution statistics
    • Pagination support for 500+ APs (tested with 949 APs)
    • Site hierarchy with automatic categorization (root/building/floor)
    • Tested with 186 configured sites across 9 areas

  • Health and troubleshooting capabilities

    • Client health aggregation (tested with 3,397 wireless clients)
    • Issue tracking with priority filtering (P1-P4)
    • Suggested remediation actions for issues
    • Compliance drift detection

  • API compatibility improvements

    • Fixed endpoint paths for DNA Center compatibility
    • Proper pagination with 1-based offset (v1 API)
    • Error handling for version-specific endpoints
    • Support for both dict and direct value response formats

  • Production testing validation

    • Tested against live DNA Center environment
    • Verified with large-scale deployment (949 APs, 3,397 clients, 186 sites)
    • All endpoints validated and working

v1.1.0 (2025-01-18)

  • Enhanced filtering capabilities
    • Added building_name parameter with automatic site ID resolution
    • Added ap_name parameter with automatic AP MAC resolution
    • Added only_active parameter for time-based filtering (last 15 minutes)
    • Added limit/offset pagination support
  • Improved data quality
    • Post-filtering for AP names ensures accuracy across DNAC versions
    • Metadata in responses (total_returned, limit_used, offset_used)
    • Pagination hints when limit is reached
  • Better user experience
    • Human-friendly parameter names (building names instead of UUIDs)
    • Last Updated timestamp in readable format
    • Smart defaults (only_active=true, limit=100)

v1.0.0 (2025-01-18)

  • Initial release with FastMCP framework
  • Single tool: get_filtered_wireless_clients
  • Token-based authentication with auto-refresh
  • Async httpx client for efficient API calls
  • Self-signed certificate support
  • Environment variable configuration