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

Install for Development

Configuration

Option 1: Environment Variables (Recommended)

Set the following environment variables:

On Windows:

Option 2: Configuration File

Create a config.json file:

Set the config file path:

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

Or use the installed script:

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:

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:

Development

Running Tests

Code Quality

Project Structure

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:

Or in config.json:

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:

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

Standalone Functions

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