Cisco Catalyst Center (DNAC) MCP Server

MCP server providing intelligent wireless client management tools for Cisco Catalyst Center (DNA Center). This server exposes DNAC wireless client queries through the Model Context Protocol (MCP), enabling AI assistants like Claude to interact with your Catalyst Center infrastructure.

Features

• 🎯 Smart Query Limiting: Automatic result limiting with configurable thresholds

• 📊 Pagination Handling: Transparent pagination for large result sets

• 💡 Actionable Guidance: Intelligent suggestions when results exceed limits

• 🔍 Rich Filtering: Filter by site, MAC, IP, SSID, band, hostname, and more

• 🏥 Health Monitoring: Detailed client health metrics and diagnostics

• ⚡ Rate Limiting: Built-in API throttling to prevent overload

• 🔒 Secure: Support for SSL verification and credential management

Installation

Prerequisites

• Python 3.10 or higher

• Access to Cisco Catalyst Center (DNAC) 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 dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Install for Development

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Format code
black src tests

# Lint code
ruff check src tests

Configuration

Option 1: Environment Variables (Recommended)

Set the following environment variables:

export DNAC_BASE_URL="https://dnac.example.com"
export DNAC_USERNAME="admin"
export DNAC_PASSWORD="your-password"
export DNAC_VERSION="2.3.7.6"  # Optional
export DNAC_VERIFY="true"      # Optional
export DNAC_MAX_RESULTS="100"  # Optional

On Windows:

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

Option 2: Configuration File

Create a config.json file:

{
  "base_url": "https://dnac.example.com",
  "username": "admin",
  "password": "your-password",
  "version": "2.3.7.6",
  "verify": true,
  "max_results": 100
}

Set the config file path:

export DNAC_CONFIG_FILE="/path/to/config.json"

Option 3: Per-Request Credentials

Pass credentials with each tool call (see Usage examples below).

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-clients": {
      "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-clients": {
      "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

1. query_wireless_clients

Query wireless clients with smart filtering and limiting.

Parameters:

• base_url (required): Catalyst Center URL (e.g., "https://dnac.example.com")

• username (required): DNAC username

• password (required): DNAC password

• site_id (optional): Filter by site UUID

• mac_address (optional): Filter by client MAC address

• hostname (optional): Filter by Access Point hostname

• ip_address (optional): Filter by client IP address

• ssid (optional): Filter by SSID name

• band (optional): Filter by frequency band (e.g., "2.4GHz", "5GHz")

• max_results (optional): Maximum clients to return (default: 100)

• version (optional): DNAC API version (default: "2.3.7.6")

• verify (optional): Verify SSL certificates (default: true)

• debug (optional): Enable debug logging (default: true)

Returns:

• clients: List of client dictionaries

• total_count: Total matching clients

• exceeded_limit: Boolean if total > max_results

• guidance: Actionable tips to refine query

• fetched_count: Actual number returned

Example Prompts for Claude:

"Show me all wireless clients"

"Find wireless clients on SSID 'Corporate-WiFi'"

"Which clients are connected to AP 'AP-Floor2-East'?"

"Show me clients with MAC address AA:BB:CC:DD:EE:FF"

"List wireless clients at site abc-123-def-456"

"Find all 5GHz wireless clients"

2. get_client_health

Get detailed health information for a specific client.

Parameters:

• base_url (required): Catalyst Center URL

• username (required): DNAC username

• password (required): DNAC password

• mac_address (required): Client MAC address

• version (optional): DNAC API version (default: "2.3.7.6")

• verify (optional): Verify SSL certificates (default: true)

Returns:

• health: Detailed health metrics

• response: Full API response data

• mac_address: Queried MAC address

Example Prompts for Claude:

"Get health details for client AA:BB:CC:DD:EE:FF"

"What's the health status of MAC address 00:11:22:33:44:55?"

"Show me detailed metrics for client AA:BB:CC:DD:EE:FF"

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_wireless_client_agent.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             # MCP server implementation
│       ├── wireless_client_agent.py  # DNAC client agent
│       └── config.py             # Configuration management
├── tests/
│   ├── __init__.py
│   ├── test_server.py
│   ├── test_wireless_client_agent.py
│   └── test_config.py
├── pyproject.toml                # Project configuration
├── requirements.txt              # Core dependencies
├── requirements-dev.txt          # Development dependencies
└── README.md                     # This file

Troubleshooting

Connection Issues

Problem: Cannot connect to DNAC Solution:

• Verify base_url is correct (do not include /api/ path)

• Check credentials

• For self-signed certificates, set verify=false

SSL Certificate Errors

Problem: SSL verification fails Solution:

export DNAC_VERIFY="false"  # For testing only

Or in config.json:

{
  "verify": false
}

No Results Returned

Problem: Query returns 0 clients Solution:

• Verify filters are correct

• Check DNAC has clients matching criteria

• Try query without filters first

• Enable debug logging: debug=true

API Version Mismatch

Problem: API calls fail with version errors Solution: Update the version parameter to match your DNAC version:

export DNAC_VERSION="2.3.5.3"  # Example

Rate Limiting

Problem: Too many API requests Solution: The server includes built-in rate limiting (0.5s delay between calls). Adjust if needed in wireless_client_agent.py.

Security Best Practices

1. Never commit credentials to version control

2. Use environment variables or secrets manager for credentials

3. Enable SSL verification in production (verify=true)

4. Use least privilege DNAC accounts (read-only if possible)

5. Rotate credentials regularly

6. Audit API access through DNAC logs

API Reference

WirelessClientAgent Class

from dnac_mcp import WirelessClientAgent
from dnacentersdk import api

# Initialize DNAC client
dnac = api.DNACenterAPI(
    base_url="https://dnac.example.com",
    username="admin",
    password="password"
)

# Create agent
agent = WirelessClientAgent(
    dnac_client=dnac,
    max_results=100,
    rate_limit_delay=0.5,
    debug=True
)

# Query clients
result = agent.get_clients(ssid="Corporate-WiFi")
print(f"Found {result['fetched_count']} clients")

Standalone Functions

from dnac_mcp import query_wireless_clients, get_client_health

# Query clients
result = query_wireless_clients(
    base_url="https://dnac.example.com",
    username="admin",
    password="password",
    ssid="Corporate-WiFi",
    max_results=50
)

# Get client health
health = get_client_health(
    base_url="https://dnac.example.com",
    username="admin",
    password="password",
    mac_address="AA:BB:CC:DD:EE:FF"
)

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository

2. Create a feature branch: git checkout -b feature-name

3. Follow TDD principles (write tests first!)

4. Follow SOLID principles in design

5. Format code: black src tests

6. Lint code: ruff check src tests

7. Run tests: pytest

8. Commit changes: git commit -am 'Add feature'

9. Push to branch: git push origin feature-name

10. Submit a Pull Request

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues

• Documentation: DNAC SDK Docs

• MCP Spec: Model Context Protocol

Acknowledgments

• Built with dnacentersdk

• Implements Model Context Protocol (MCP)

• Inspired by Cisco DevNet community

Roadmap

• Add support for wired clients

• Implement client troubleshooting tools

• Add network device queries

• Support for client statistics and trends

• Webhook notifications for client events

• GraphQL query support

• Multi-site aggregation

• Export to CSV/JSON

Changelog

v1.0.0 (2025-01-XX)

• Initial release

• Wireless client query with smart limiting

• Client health monitoring

• MCP server implementation

• Configuration management

• Comprehensive documentation