| name | catc-client-ops |
| description | Catalyst Center client operations and monitoring - list/filter wired and wireless clients, detailed client lookup by MAC, client count analytics, time-based analysis, SSID and band filtering, wireless troubleshooting. Use when looking up a client by MAC or IP, counting clients per site or SSID, analyzing wireless band distribution, or investigating Wi-Fi signal issues. |
| license | Apache-2.0 |
| user-invocable | true |
| metadata | {"openclaw":{"requires":{"bins":"[Truncated]","env":"[Truncated]"}}} |
Catalyst Center Client Operations and Monitoring
Catalyst Center MCP Server
All Catalyst Center tool calls use this invocation pattern:
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 -u $CATC_MCP_SCRIPT
Variable shorthand used throughout this document:
CATC_CMD="CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 -u $CATC_MCP_SCRIPT"
How to Call Tools
Use the $MCP_CALL protocol handler to invoke MCP tools:
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" TOOL_NAME 'ARGS_JSON'
When to Use
- Monitoring wired and wireless client populations
- Investigating specific client connectivity issues by MAC address
- Capacity planning: how many clients per site, SSID, or band
- Wireless troubleshooting: signal quality, RSSI, band steering analysis
- Time-based analysis: client count trends over hours/days
- Security investigations: locate a client by IP or MAC across the network
- Help desk escalations: look up a user's device and connection details
- SSID utilization and OS distribution analytics
Critical: Time Range Handling
The Catalyst Center client APIs require startTime and endTime in epoch milliseconds. The API enforces a 30-day maximum lookback for startTime.
ALWAYS call get_api_compatible_time_range FIRST to convert human-readable time ranges into valid epoch millisecond pairs before calling any client tool.
get_api_compatible_time_range -- Convert Time Ranges
Parameters:
time_window (string, optional): Human-readable relative time. Examples: "last 2 hours", "last 7 days", "today", "yesterday", "last 30 days". Takes precedence over ISO params if provided.start_datetime_iso (string, optional): Specific start in ISO 8601 format (e.g., "2025-01-15T10:00:00Z")end_datetime_iso (string, optional): Specific end in ISO 8601 format. Defaults to now if omitted.
Returns: JSON with startTime and endTime (epoch ms), adjusted_for_30_day_limit flag, and ISO timestamps for verification.
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"last 2 hours"}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"start_datetime_iso":"2025-01-15T08:00:00Z","end_datetime_iso":"2025-01-15T17:00:00Z"}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"today"}'
IMPORTANT: If the response shows adjusted_for_30_day_limit: true, the requested start time exceeded the API's 30-day limit and was automatically clamped. Inform the user that the effective time range is shorter than requested.
Available Client Tools
1. get_clients_list -- List Connected Clients
Retrieves a list of clients from the /dna/data/api/v1/clients endpoint. Hard limit of 100 clients per call. If more than 100 clients match the filters, the tool returns the total count and a message requesting more specific filters instead of partial data.
Parameters:
| Parameter | Type | Description |
|---|
start_time | int | Epoch ms start time (use get_api_compatible_time_range) |
end_time | int | Epoch ms end time |
limit | int | Max clients to return (default 100, capped at 100) |
offset | int | Starting record for pagination (default 1) |
sort_by | str | Attribute to sort by (e.g., clientConnectionTime) |
order | str | asc or desc (default asc) |
client_type | str | "wired" or "wireless" |
os_type | List[str] | OS filter: ["Windows"], ["macOS"], ["Android"], etc. |
os_version | List[str] | OS version filter |
site_hierarchy | List[str] | Full site path: ["Global/USA/NYC/Floor2"] |
site_hierarchy_id | List[str] | Site hierarchy UUID(s) |
site_id | List[str] | Site UUID(s) |
ipv4_address | List[str] | Client IPv4 address(es) |
ipv6_address | List[str] | Client IPv6 address(es) |
mac_address |
List type parameters (os_type, site_hierarchy, ssid, band, etc.) must be passed as JSON arrays of strings: ["value1","value2"].
2. get_client_details_by_mac -- Detailed Client Info by MAC
Fetches comprehensive details for a single client identified by MAC address from the /dna/data/api/v1/clients/{mac} endpoint.
Parameters:
client_mac_address (string, required): The MAC address of the clientstart_time (int, optional): Epoch ms start timeend_time (int, optional): Epoch ms end timeview (List[str], optional): Additional data viewsattribute (List[str], optional): Specific attributes
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_client_details_by_mac '{"client_mac_address":"AA:BB:CC:DD:EE:FF"}'
Response includes: Client MAC, IP address, hostname, OS type/version, connected device name, connected interface, VLAN, SSID (if wireless), band, channel, RSSI, SNR, data rate, connection time, health score, and more.
Automatic retries: If the API returns error code 14006 (data not ready for the requested endTime), the tool automatically retries with the API-suggested adjusted endTime.
3. get_clients_count -- Count Clients Matching Filters
Returns the total count of clients matching the specified filters from the /dna/data/api/v1/clients/count endpoint. Use this for analytics and capacity planning without retrieving full client records.
Parameters: Same filter parameters as get_clients_list (except limit, offset, sort_by, order, view, attribute).
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless"}'
Client Operations Workflows
Workflow 1: Find All Wireless Clients on a Specific SSID
Step 1: Get the time range
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"last 2 hours"}'
Extract startTime and endTime from the response.
Step 2: Count clients on the SSID first
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","ssid":["Corporate-WiFi"]}'
If count > 100, narrow with additional filters (site, band, OS) before listing.
Step 3: List the clients
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","ssid":["Corporate-WiFi"]}'
If count exceeded 100, narrow by site:
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","ssid":["Corporate-WiFi"],"site_hierarchy":["Global/USA/NYC/Floor2"]}'
Workflow 2: Investigate a Client by MAC Address
Full client investigation for help desk escalation or security incident.
Step 1: Get the time range
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"last 24 hours"}'
Step 2: Fetch detailed client info
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_client_details_by_mac '{"client_mac_address":"AA:BB:CC:DD:EE:FF","start_time":1705312800000,"end_time":1705399200000}'
Step 3: With additional wireless views
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_client_details_by_mac '{"client_mac_address":"AA:BB:CC:DD:EE:FF","start_time":1705312800000,"end_time":1705399200000,"view":["Wireless","WirelessHealth"]}'
Analyze the results:
- Connection state: Is the client currently connected? What is the connection time?
- Network attachment: Which switch/AP is it connected to? Which interface/SSID?
- IP assignment: Does it have a valid IP? DHCP or static?
- Health score: Client health score (0-10). Below 7 indicates issues.
- For wireless clients: RSSI, SNR, channel, band, data rate, AP name
- OS information: OS type and version for security posture assessment
Workflow 3: Count Clients Per Site
Build a site-by-site client distribution report.
Step 1: Get the time range
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"last 1 hours"}'
Step 2: Get the site hierarchy
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" fetch_sites '{}'
Step 3: Count clients at each site
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"site_hierarchy":["Global/USA/NYC"]}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"site_hierarchy":["Global/USA/CHI"]}'
Step 4: Break down by wired vs wireless per site
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"site_hierarchy":["Global/USA/NYC"],"client_type":"wired"}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"site_hierarchy":["Global/USA/NYC"],"client_type":"wireless"}'
Build the report:
Client Distribution Report
===========================
Catalyst Center: $CCC_HOST
Time Window: Last 1 hour (2025-01-15 14:00 - 15:00 UTC)
+----------------------------+-------+--------+----------+-------+
| Site | Total | Wired | Wireless | %WiFi |
+----------------------------+-------+--------+----------+-------+
| Global/USA/NYC | 1,245 | 320 | 925 | 74.3% |
| NYC/Floor1 | 412 | 110 | 302 | 73.3% |
| NYC/Floor2 | 498 | 130 | 368 | 73.9% |
| NYC/Floor3 | 335 | 80 | 255 | 76.1% |
| Global/USA/CHI | 876 | 250 | 626 | 71.5% |
| Global/USA/LAX | 534 | 180 | 354 | 66.3% |
+----------------------------+-------+--------+----------+-------+
| TOTAL | 2,655 | 750 | 1,905 | 71.8% |
+----------------------------+-------+--------+----------+-------+
Workflow 4: Time-Based Client Trend Analysis
Analyze how client counts change over time for capacity planning or anomaly detection.
Step 1: Define time windows (e.g., hourly snapshots over the last 8 hours)
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"last 8 hours"}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"start_datetime_iso":"2025-01-15T06:00:00Z","end_datetime_iso":"2025-01-15T07:00:00Z"}'
Step 2: Count clients for each time window
Run get_clients_count for each hourly window with the appropriate start_time and end_time values.
Build the trend report:
Client Count Trend (Wireless)
==============================
Site: Global/USA/NYC
Date: 2025-01-15
Hour (UTC) | Count | Delta | Bar
--------------+--------+--------+---------------------------
06:00 - 07:00 | 245 | -- | ============
07:00 - 08:00 | 512 | +267 | =========================
08:00 - 09:00 | 891 | +379 | ============================================
09:00 - 10:00 | 1,102 | +211 | ======================================================
10:00 - 11:00 | 1,189 | +87 | ===========================================================
11:00 - 12:00 | 1,156 | -33 | =========================================================
12:00 - 13:00 | 987 | -169 | =================================================
13:00 - 14:00 | 1,134 | +147 | ========================================================
Peak: 1,189 clients at 10:00-11:00 UTC
Trough: 245 clients at 06:00-07:00 UTC
Workflow 5: OS Distribution Analysis
Understand the client OS mix for security posture and compatibility planning.
Step 1: Get time range
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"last 1 hours"}'
Step 2: Count clients per OS type
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["Windows"]}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["macOS"]}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["iOS"]}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["Android"]}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["Linux"]}'
Workflow 6: Wireless Band Distribution
Analyze the 2.4 GHz vs 5 GHz vs 6 GHz client distribution for RF planning.
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","band":["2.4GHz"]}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","band":["5GHz"]}'
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","band":["6GHz"]}'
RF planning flags:
- More than 40% of clients on 2.4 GHz -> WARNING: Poor band steering, co-channel interference risk
- 5 GHz utilization > 80% of wireless clients -> HEALTHY: Good band steering configuration
- 6 GHz adoption < 5% when Wi-Fi 6E APs are deployed -> INFO: Check client capability and SSID configuration
Workflow 7: Find a Client by IP Address
Locate a client on the network when you only know the IP (common for security investigations).
Step 1: Get the time range
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"last 4 hours"}'
Step 2: Search by IP
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"ipv4_address":["10.1.50.42"]}'
Step 3: Get full details using the MAC from the response
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_client_details_by_mac '{"client_mac_address":"AA:BB:CC:DD:EE:FF","start_time":1705312800000,"end_time":1705399200000}'
Workflow 8: Clients Connected to a Specific Network Device
Identify all clients connected through a particular switch or AP.
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"connected_network_device_name":["ACC-SW-01"]}'
Workflow 9: Clients on a Specific WLC
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"wlc_name":["WLC-NYC-01"]}'
Wireless Client Troubleshooting Reference
When investigating wireless client issues, use get_client_details_by_mac with the Wireless and WirelessHealth views and examine these key metrics:
RSSI (Received Signal Strength Indicator)
| RSSI (dBm) | Quality | Action |
|---|
| -30 to -50 | Excellent | No action needed |
| -50 to -60 | Good | Acceptable for all applications |
| -60 to -67 | Fair | VoIP may experience quality issues |
| -67 to -70 | Weak | Consider AP placement or power adjustment |
| -70 to -80 | Very Weak | Roaming and throughput issues likely |
| Below -80 | Unusable | Client will disconnect or fail to associate |
SNR (Signal-to-Noise Ratio)
| SNR (dB) | Quality | Action |
|---|
| > 40 | Excellent | No action needed |
| 25-40 | Good | Acceptable |
| 15-25 | Fair | May impact higher data rates |
| 10-15 | Poor | Significant throughput degradation |
| < 10 | Unusable | Noise floor investigation required |
Common Wireless Client Issues
| Symptom | Likely Cause | Investigation |
|---|
| Low RSSI | Client too far from AP, physical obstructions | Check AP location, consider adding AP |
| Low SNR with OK RSSI | High noise floor | Check for interferers (microwave, Bluetooth, rogue APs) |
| Frequent disconnects | Sticky client, aggressive roaming | Check roaming threshold, 802.11r/k/v config |
| Slow throughput | Band steering failure, co-channel interference | Check band distribution, channel plan |
| Authentication failures | 802.1X/RADIUS issue | Check ISE logs, certificate validity |
| DHCP failure | Scope exhaustion, VLAN mismatch | Check DHCP scope, verify VLAN assignment |
Client Operations Report Format
Client Operations Report
=========================
Catalyst Center: $CCC_HOST
Time Window: 2025-01-15 14:00 - 15:00 UTC
Client Overview
---------------
Total Connected: 2,655
Wired: 750 (28.2%)
Wireless: 1,905 (71.8%)
Wireless Band Distribution
---------------------------
2.4 GHz: 285 (15.0%) -- HEALTHY (below 30% threshold)
5 GHz: 1,502 (78.8%) -- HEALTHY
6 GHz: 118 (6.2%) -- HEALTHY (Wi-Fi 6E adoption growing)
Top SSIDs
----------
Corporate-WiFi: 1,245 clients (65.4%)
Guest-WiFi: 412 clients (21.6%)
IoT-Devices: 248 clients (13.0%)
OS Distribution
----------------
Windows: 1,102 (41.5%)
macOS: 534 (20.1%)
iOS: 445 (16.8%)
Android: 312 (11.8%)
Linux: 98 (3.7%)
Other: 164 (6.2%)
Site Distribution
------------------
Global/USA/NYC: 1,245 (46.9%)
Global/USA/CHI: 876 (33.0%)
Global/USA/LAX: 534 (20.1%)
GAIT Audit Trail
After completing any client operations session, record the findings in GAIT:
python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_record_turn '{"input":{"role":"assistant","content":"Catalyst Center client operations on $CCC_HOST: 2,655 total clients (750 wired, 1,905 wireless). Band distribution healthy: 15% on 2.4GHz, 79% on 5GHz, 6% on 6GHz. Top SSID: Corporate-WiFi (1,245 clients). OS mix: Windows 42%, macOS 20%, iOS 17%. No anomalies detected in the last 1-hour window.","artifacts":[]}}'
