Writing and running MQ applications on your Mac

The MacOS Toolkit lets you develop MQ applications on your Mac and interact directly with the MQ server running elsewhere. As a developer, you can use the language interfaces which are built on the platform-native C library (libmqm): C, C++, COBOL, GoLang, and Node.js.

The IBM MQ MacOS Toolkit is similar to IBM MQ Clients for different platforms and to IBM MQ redistributable clients. Unlike the clients, the toolkit is provided for development purposes only. Applications built with it are not supported in production and unlike the redistributable clients, the MacOS Toolkit cannot be distributed with applications.

The Toolkit includes native client runtime libraries, so you can run IBM MQ applications that can use the MQ API – Message Queue Interface (MQI). It also includes the elements required to build C based language applications.

With the MacOS Toolkit, you can:

  • Develop MQ applications natively on your Mac, using the provided C libraries to compile and unit test your code.
  • Run many of the existing MQ samples, such as amqsput and amqsget.
  • Administer your queue manager with MQSC commands through the provided runmqsc tool, whether the queue manager is running in a Docker container, Cloud platform, VM, or a supported on-premise solution.
  • Use mqrc to get extra information on any error you see with MQ.
  • Use the new Node.js bindings, Go bindings, and JMS-like API for Golang, which all build on the full C MQI library.



  1. Download the MacOS Toolkit
  2. Set up the MacOS Toolkit
  3. Try some of the sample applications
  4. Check that my messages made it onto a queue

Step 1. Download the MacOS Toolkit

Accept the license for developers to download the IBM MQ MacOS toolkit, and the toolkit is downloaded to your system.

Step 2. Set up the MacOS Toolkit

After downloading the toolkit to your Mac, double-click on the downloaded .pkg file and follow the installation steps.

Add the location of the bin directories to the PATH, by editing /etc/paths.

  • /opt/mqm/bin
  • /opt/mqm/samp/bin

You can test that the toolkit works by running dspmqver in a terminal. You should see the MQ version number, plus some other data, for example the installation path.

The MacOS Toolkit needs a data folder for errors and other files. The default data path is $HOME/IBM/MQ/data. You can change the default directory of the data path, by using the MQ_OVERRIDE_DATA_PATH environment variable; however, you must create the directory first.

Step 3. Try some of the sample applications

Before you can try a sample application, you need to stand up a queue manager and a queue. If you don’t have them set up already, complete the steps in the “Get an IBM MQ queue for development in a container” tutorial, or provision one in IBM Cloud by completing the steps in the “Get an IBM MQ queue for development in IBM Cloud” tutorial.

Then, take a look at this IBM Messaging samples and patterns GitHub repository and try the Python, Node.js or Golang samples. We figured you already know you can develop on a Mac if you’re using JMS, so we’ve provided libraries for JMS on Maven for a while now. There are instructions in the readme docs for each language.

If you are familiar with MQ, you will find the packaged samples in: /opt/mqm/samp/bin

Step 4. Check that my messages made it onto a queue

So, you have a queue manager, and you’ve managed to put some messages on a queue, but you’d like to check whether the message made it onto a queue. You can either use the MQ Console in a browser or you can use the MQ Explorer.

Viewing messages in MQ Console in a browser

You can use MQ Console in your browser to check whether the message has made it onto a queue.

If you’re using Docker to stand up your queue manager, MQ console should already be configured. Go to https://localhost:9443/ibmmq, and log in with the default credentials. See Step 4 in “Get an IBM MQ queue for development in a container” tutorial to learn how to browse messages on your queue using the MQ Console.

If you’re using MQ on Cloud to provision your queue manager, see Administering a queue manager using IBM MQ Web Console. Follow instructions on the same page to browse messages on your MQ on Cloud queue.

Viewing messages in MQ Explorer in Eclipse

You can also use the MQ Explorer to connect to the queue manager and check your queue and messages. There is an MQ Explorer plug in for Eclipse.

  1. Visit the Eclipse market place and identity a suitable Eclipse version for your MacOS environment.

  2. If you need to install a version of Eclipse to host the IBM MQ Explorer plugin, then visit the Eclipse download page, select R Packages, and download the Eclipse IDE.

  3. From the Eclipse marketplace MQ Explorer page, click the fourth orange download icon under the install by dragging button.

  4. From the pop-up that appears, copy the URL that you need for Eclipse.

  5. Open Eclipse.

  6. From the Help menu for Eclipse, go to Install new software.

  7. In Eclipse Install window, in the Work with field, paste the link you just copied from Eclipse Marketplace MQ Explorer page. MQ Explorer appears as a list item in the Name/Version box.

  8. Click Finish. The Explorer interface appears. (You might need to restart your Eclipse.)

If you’re using a different version of Eclipse, the Explorer interface might not immediately open.

If so, Click Windows -> Perspective -> Open Perspective -> MQ Explorer. The MQ Explorer interface should now appear.

To add your queue manager in MQ Explorer, complete these steps:

  1. Right-click Queue managers in the MQ Explorer Navigator box, and then select Add remote queue manager. A pop up appears.
  2. Add your queue manager name. If Docker, use QM1. Then, click Next.
  3. Add Host name or IP Address. If Docker, use localhost.
  4. Add Server connection channel. If Docker, use DEV.ADMIN.SVRCONN. Then, click Next twice.
  5. Check Enable user identification. If Docker, the default is admin. Leave Prompt for password selected.
  6. Click Finish.
  7. Add the password for user. If Docker, use passw0rd. Your queue manager should appear.

To check that the message you sent from your application has made it, see Verifying that the test message was sent in the documentation.

If you run into issues with MQ Explorer, and the Eclipse version you have is not 4.7.3a, you might have to uninstall the version that you have and roll back or up to eclipse-SDK-4.7.3a-macosx-cocoa-x86_64.dmg.

Summary and next steps

In this tutorial, you learned what you can do with the MacOS Toolkit, how to use it, and where to find the samples to connect to the queue manager and put and get messages to and from a queue. If your queue manager is running in Docker or you’ve provisioned it in IBM Cloud, you can use MQ Explorer on your Mac or MQ Console in the browser to check your messages have made it on the queue.