merakicat 1.2.2

An app to check and translate Catalyst switch configs to Meraki.

merakicat

This package makes migrating Cisco Catalyst switches to Meraki Dashboard much easier. #merakicat

This Python app can be run in Webex Teams Bot mode or in command-line mode.

Below is the list of configurations the tool can currently translate:

switch:

• Hostname
• Spanning Tree RSTP
• Stack
• Static Routing

port:

• Port Description
• Port Status
• Port Speed
• Port Duplex
• Port Type
• PoE Enabled
• Allowed VLANs
• Data VLAN
• Voice VLAN
• Private VLAN
• Layer 3 Interface
• STP RootGuard
• STP Loop Guard
• STP BPDU Guard
• Etherchannel LACP
• NM Ports

Once installed, you can print the entire index of the feature encyclopedia, or to print the index based on either supported and translatable items or both, enter:

cd src/merakicat
python mc_pedia [support] [translatable]

Prerequisites for using in Bot mode

If you don't already have a Webex Teams account, go ahead and register for one. They are free.

1. You'll need to start by adding your Bot to the Webex Teams website.

   https://developer.webex.com/my-apps

2. Click Create a New App

   

3. Click Create a Bot.

   

4. Fill out all the details about your Bot. You'll need to set a name, username, icon (either upload one or choose a sample), and provide a description.

   

5. Click Add Bot.

6. On the Congratulations screen, make sure to copy the Bot's Access Token, you will need this in a second.

   

Installation

Python 3.11 is recommended.

• Clone the github repository and install the requirements

git clone https://github.com/ecoen66/merakicat
cd merakicat
pip install -r requirements_dev.txt

Usage

• The easiest way to use this module is to set a few environment variables

• You can also put the same KEY=value entries in a .env file (see .env.example).

  Note: As an alternative, you may edit the variables in mc_user_info.py. Although more convenient, it is less secure.

  # These exports are used for Webex bot mode:
  export TEAMS_BOT_TOKEN=<your bot's token>
  export TEAMS_BOT_EMAIL=<your bot's email>
  export TEAMS_BOT_APP_NAME=<your bot's name>
  export TEAMS_EMAILS=<a comma delimited list of email addresses the bot will respond to>
  
  # These exports are required regardless of mode:
  export IOS_USERNAME=<the ssh username for the Catalyst switches>
  export IOS_PASSWORD=<the ssh password for the Catalyst switches>
  export IOS_SECRET=<the CLI secret password for the Catalyst switches>
  export IOS_PORT=<the ssh port number for the Catalyst switches - usually 22>
  export MERAKI_API_KEY=<your meraki dashboard API key>
  export MERAKI_ORG_NAME =<your meraki organization name>
  

In addition to these settings, various debugs and a choice of PDF vs. DOCX report format can be enabled in the mc_user_info.py file.

> Note: For PDF report generation, MS Word must be installed on the host with merakicat.

Bot

To run merakicat as a Bot, just start it without any parameters:

cd src/merakicat
python merakicat.py

Bot commands include the following:

Check a Catalyst switch config for both translatable and possible Meraki features:

check [host <FQDN or IP address> | file <filespec>] [with timing] [with details]

Check one or more Catalyst switch config files for both translatable and possible Meraki features:

check <drag-and-drop files> [with timing] [with details]

Check the configs of cloud monitored Catalyst switches for both translatable and possible Meraki features:

check network <Meraki network name> [with timing] [with details]

Register a Catalyst switch to the Meraki Dashboard:

register [host <FQDN or IP address>] [with timing]

Claim Catalyst switches to a Meraki Network:

claim [<Meraki serial numbers>] [to <Meraki network name>] [with timing]

Translate a Catalyst switch config from a file or host to claimed Meraki serial numbers:

translate [host <FQDN or IP address> | file <filespec>] [to <Meraki serial numbers>] [with timing]

Migrate a Catalyst switch to a Meraki switch - register, claim & translate:

migrate [host <FQDN or IP address>] [to <Meraki network name>] [with timing]

List all Meraki networks in the configured organization:

get networks

Create a demo report for all features currently in the feature encyclopedia:

demo report

Command-line

To run merakicat from the command-line (or from a shell script), enter any of the following:

Check a Catalyst switch config for both translatable and possible Meraki features:

cd src/merakicat
python merakicat.py check host <FQDN or IP address> | file <filespec> [with timing] [with details]

Check a list of switches specified in a CSV or Excel file (use hosts_template.xlsx as a template):

cd src/merakicat
check hosts <filespec> [with timing]

Check the configs of cloud monitored Catalyst switches for both translatable and possible Meraki features:

cd src/merakicat
python merakicat.py check network <Meraki network name> [with timing] [with details]

Get the Cloud ID for a Catalyst switch:

cd src/merakicat
python merakicat.py get cloud-id <FQDN or IP address> [with timing]

Get Cloud IDs for hosts listed in a CSV or Excel file (use hosts_template.xlsx as a template):

cd src/merakicat
python merakicat.py get cloud-ids <filespec> [with timing]

List all Meraki networks in the configured organization:

cd src/merakicat
python merakicat.py get networks

Register a Catalyst switch or stack to the Meraki Dashboard:

cd src/merakicat
python merakicat.py register host <FQDN or IP address> [with timing]

Claim Catalyst switches to a Meraki Network:

cd src/merakicat
python merakicat.py claim <Meraki serial numbers> to <Meraki network name> [with timing]

Translate a Catalyst switch or stack config from a file or host to claimed Meraki serial numbers:

cd src/merakicat
python merakicat.py translate host <FQDN or IP address> | file <filespec> to <Meraki serial numbers> [with timing]

Migrate a Catalyst switch to a Meraki switch - register, claim & translate:

cd src/merakicat
python merakicat.py migrate host <FQDN or IP address> to <Meraki network name> [with timing]

Create a demo report for all features currently in the feature encyclopedia:

cd src/merakicat
python merakicat.py demo report

Bulk-mode

To run merakicat in bulk-mode, create a shell script to call merakicat in command line mode. Example scripts included in the repo are:

Migrate a list of Catalyst switches to a Meraki network, 20 switches at a time, until the entire list is exhausted. The list is provided in an input file, one hostname/fqdn/IP address per line:

cd src/merakicat
bulk_migrate.sh <input file> <Meraki network name>

Donations

If you found this repo to be useful, please consider donating to Life Decisions, Rockford, IL through a purchase from the Merakicat store.

Credits

This project is heavily based on the work of others:

Catalyst_to_Meraki_Migration_Tool by Fady Sharobeem.

Catalyst_2_Meraki_Config_Checker by Fady Sharobeem.

The bot functionality is using webex_bot by Finbarr Brady.

Thanks to contributors for keeping the project alive and useful:

ganuzelli & DrewAeg

History

1.2.2 (6-26-2026)

• Removed duplicate mc_pedia2.py file from repo root
• Patched mc_prechecks.py to account for an unconfigured, default VLAN 1

1.2.0 (6-22-2026)

• Added a "get networks" command that lists all the networks in the org
• Added support for using a .env file to store secrets
• Added switch model and IOS version compatibility checks
• Added the runtime checks performed by "register" to the reports generated by "check host(s)"
• Modified "get cloud-id(s)" to be more robust and to skip compatibility checks normally performed by "register" to ensure Cloud IDs are reported.
• Refactored mc_register.py and some other files in order to better support these changes.

1.1.0 (4-30-2026)

• Added check hosts, get cloud-id, and get cloud-ids commands (currently CLI mode only).
• Removed references to bulk_check.sh which has been replaced by check hosts.
• Added checks in Register() to see if the switch has already been claimed in the Dashboard, or if the switch already has a Cloud ID before registering the switch to generate one. This speeds up the process for those two cases and protects against initiating a migration to Cloud Managed if the switch is already claimed an in a network.
• Started implementing a --dry-run feature. Not exposed in help because it a work in progress.
• Fix issue with determining the Organization ID if the user has access to more than one org.
• Added support for IE-3500 series switches

1.0.1 (11-16-2025)

• Fixed issue with single switch "stacks".
• Fixed issue where switches on unified versions of IOS XE would automatically reboot into Meraki mode.
• Added compatibility with Early Adopters version of Meraki Dashboard API for unified IOS XE onboarding.
• Fixed issue with special versions of IOS XE.
• Reformatted the encyclopedia for easier updates and readability.
• Renamed the new encyclopedia, as it is no longer compatible with earlier versions of Merakicat.
• Updated requirements

0.2.7 (03-23-2025)

• Resolved issue with C9K Uplink after API change.
• mc_pedia version 0.1.78

0.2.6 (05-07-2024)

• Resolved Issue #6.
• Fixed issue with unclaiming switches before removing switch stack.
• Updated requirements.

0.2.5 (04-25-2024)

• Reverted back to Finbarr Brady's webex-bot after a pull merge.

0.2.4 (04-12-2024)

• Added Private VLAN -> Port Isolation to encyclopedia.
• Removed older bot code.
• Updated AUTHORS.rst.
• Updated .gitignore

0.2.3 (04-10-2024)

• Translate now checks to make sure that the target switches have the same number of ports as the sources.

0.2.2 (04-10-2024)

• Added environment variable to specify a Meraki Oragnization name.

0.2.1 (04-10-2024)

• Added support for ip default-gateway as a static route.

0.2.0 (04-10-2024)

• Changed BOT libraries to enable websockets and remove ngrok for security.
• Began adding logic for Catalyst Cloud Monitoring onboarding.

0.1.8 (04-03-2024)

• Edited README.
• Renamed mc_user_sample.py to mc_user_info.py and commented out possible environment variables.
• Added logic to merakicat.py to handle missing variables on import from mc_user_info.py.

0.1.7 (04-01-2024)

• Added the ability to Check the configs of cloud monitored Catalyst switches for both translatable and possible Meraki features.
• Included "with timing" and "with details" options on check drag-n-drop.
• Renamed some called functions in external modules.

0.1.6 (03-26-2024)

• Updated encyclopedia.
• Migrated batch helper code for cleaner installation.

0.1.5 (03-23-2024)

• Supports NM ports.
• Merged nm-specifics into the encyclopedia.

0.1.4 (03-21-2024)

• Downloads a fresh copy of the encyclopedia from my repo if the local copy is over 24 hours old.

0.1.3 (03-21-2024)

• Code beautification with flake8.
• Setting up for publishing automation.
• Changed directory structure for publishing.
• Released on PyPI.

0.0.14 (03-19-2024)

• Option added for check with drag and drop files in bot mode.
• Added missing timing in check report in bot mode.
• Still not yet released on PyPI.

0.0.13 (03-18-2024)

• Option added for detailed check report "with detail".

0.0.12 (03-15-2024)

• Option for PDF vs. DOCX reporting in checker.
• Layer 3 Interfaces (interface VLAN) supported.
• Static routes supported.
• Command added for "demo report".

0.0.11 (03-12-2024)

• New reporting in checker.
• Port-channel LACP is working and fast.

0.0.10 (03-08-2024)

• Using a single mc_pedia.

0.0.9 (03-07-2024)

• Using both config_pedia and check_pedia.
• Changed to ngrok API for bot functionality

0.0.8 (03-01-2024)

• Lots of comment blocks added.

0.0.7 (03-01-2024)

• Now using batch port updates to Meraki dashboard.

0.0.6 (03-01-2024)

• Some light refactoring of mc_translate module.
• More prep work for Uplink config.

0.0.5 (02-29-2024)

• Added Catalyst NM module recognition and prep work for Uplink config.

0.0.4 (02-28-2024)

• Removed external data fetch for list of unsupported features in prep for adding display of features that are semi-supported.
• Added command line help python merakicat.py help.

0.0.3 (02-27-2024)

• Created command line option vs BOT.
• Just try python merakicat.py convert host to .

0.0.2 (02-26-2024)

• Not yet released on PyPI.

0.0.1 (02-26-2024)