Install the MTConnect Agent In Two Easy-ish Steps

Install the MTConnect Agent In Two Easy-ish Steps

A step-by-step guide to installing and configuring the MTConnect Agent, and an update to my earlier article, “Set up an MTConnect Agent in three or so steps“.


Make sure your machine tools are MTConnect-ready

In the ten or so years since MTConnect emerged, this step has become much easier, as most machine-tool manufacturers support the standard in some way.

This may require additional hardware, e.g. for older machine tools where it may be necessary to integrate with a PLC or some type of I/O block. Or it may be a simple software option, such as through Fanuc FOCAS, Okuma THINC, or by adapting from another existing data provider, such as OPC.

The (very useful) MTConnect User’s Portal hosts a page listing supported functionality for several manufacturers, to give you an idea of what data you might extract from your machine tool.

Whatever the case, your local distributor or tool manufacturer can tell you what options are available to integrate your machine tool with an MTConnect ecosystem.

Choose your host platform

Where are you installing the MTConnect Agent?

A Linux server? That might mean anything from an Amazon EC2 cloud server, to a Raspberry Pi sitting on Jim’s desk. (Hi, Jim.)

In this case, you’ll need to be comfortable with the command-line. You don’t need to be an expert, but you will need to install prerequisite packages (through aptitude, yum, rpm, or whichever tool your distribution uses), edit configuration files, and run from the shell prompt.

A Windows machine? Again, that might be anything from a Windows Server 2019 box, to Jim’s old WinXP laptop. (Hi again, Jim.) Pre-built binaries are available for Windows, which means you won’t need to build it yourself.

Oh, and speaking of Jim’s old WinXP laptop…

Consider your security requirements

To be at all useful, the MTConnect Agent needs to be able to talk to your machine tools (or at least the adapters that are themselves connected to your machine tools) over the network.

I’ve seen machine shops whose network consisted of a single off-the-shelf wifi router. I’ve also seen machine shops whose network was a highly layered and isolated system managed by a full-time IT staff.

There is no way to generalize about this. But if you are the one-man IT department for your company, keep in mind that the data traveling from an MTConnect Adapter to an MTConnect Agent (SHDR protocol) and the data served by the MTConnect Agent (HTTP protocol) are sent as unencrypted cleartext.

Step 1 – Install the MTConnect Agent

On Debian Linux

Install the prerequisite packages. Elevate privileges and run:

apt install libxml2 libxml2-dev cmake git build-essential libcppunit-dev

Then pull the MTConnect Agent source code from GitHub:

git clone

Build the agent. (If you’re on a low-powered system like a Raspberry Pi, this will take a long time.)

cd cppagent

cmake .


You should then be able to run the agent, and see it listening on port 5000.

cd agent

./agent daemonize

netstat -anp –tcp

PID 4084, “agent”, is listening on TCP port 5000, on all interfaces.

If you need further proof, try to fetch the device list and current state from the running agent:

wget localhost:5000

wget localhost:5000/current

You should now have two files in your working directory: index.html contains the device list, and current contains the current status.

On Windows

In a browser, navigate to the MTConnect Agent download page and download the current release.

It’s called “Vista”, but you probably want it for Win8, Win10, or any Windows Server from the last ten years.

Extract the ZIP file to wherever you want to install the agent. (For example, into “C:\Program Files\MTConnect Agent”.)

Then run a CMD window as administrator. Change directory to the bin/ path, and run the agent’s “install” routine, then its “run” routine.

cd “C:\Program Files\MTConnect Agent\bin\”

.\agent.exe install

.\agent.exe run

In your browser, you should be able to access the agent on port 5000:

Step 2 – Configure the MTConnect Agent

The “agent.cfg” file contains all configuration for the agent. Edit the file using the text editor of your choice. (I personally like Notepad++ on Windows, and nano on Linux.) The configuration file is in something called Boost C++ file format, and should look reasonably familiar if you’ve used JSON or YAML.

The readme contains a complete description of all configuration options, but let’s break down the default configuration so you can see what might need to change:

Devices = ../simulator/VMC-3Axis.xml

This tells the agent where to look for the Devices file, which is an XML file containing a complete description of the data the agent will serve. You will need to create a Devices XML file that includes all of your devices.

This might sound complicated, but your machine tool’s MTConnect adapter should also come with a sample device description that you can copy and paste.

One important thing to remember is that all of the “id” attributes must be unique throughout the entire file. So if you have two machine tools that each define an axes component as “<Axes id=”ax” name=”Axes”>”, then you should change the IDs to “ax1” and “ax2”.

AllowPut = true
ReconnectInterval = 1000
BufferSize = 17
SchemaVersion = 1.4

These lines tell the agent to allow HTTP PUT requests (an alternate method of updating data), to attempt to reconnect to the adapters every 1000 ms (or every one second), to maintain the last 17 data item changes in its buffer, and that it is running schema version 1.4.

You’ll probably want to bump up the buffer size.

Adapters { 
VMC-3Axis {
Host = ::1
Port = 7878

The “Adapters” section tells the agent about all of the adapters it should connect to.

In this case, it connects to one adapter, named “VMC-3Axis”. The Host parameter tells it the hostname of the adapter: “::1” is IPv6 shorthand for “localhost”, but you can also give it an IPv4 address or a hostname. Port 7878 is the default port for an MTConnect adapter.

You will need to add an entry for each of the adapters that the MTConnect Agent should connect to.

Files {
schemas {
Path = ../schemas
Location = /schemas/
styles {
Path = ../styles
Location = /styles/
Favicon {
Path = ../styles/favicon.ico
Location = /favicon.ico

The “Files” section tells the agent about additional static files that it should serve. In this case, it also serves schemas and styles for the agent, and a favicon to display in the browser’s location bar.

If you want to serve a web-based MTConnect viewer, this is a good place to specify it.

StreamsStyle {
Location = /styles/Streams.xsl

This section tells the agent that there is an XSL (a document that can style an XML file) to use when displaying Streams. You can also specify a stylesheet for Devices, Assets, and Error responses.

# Logger Configuration
logging_level = debug
output = cout

The agent will write logging messages to its default output. This tells the agent to log all messages at a level of “debug” or higher. The levels are “trace”, “debug”, “info”, “warn”, “error”, and “fatal”.

When going into production, you may wish to raise this up to “warn” so that you don’t fill up your log with debugging information.

You’ll also want to change the output, because “cout” means output to the console window. You can write to a file by specifying:

output = file log.txt

Incidentally, that ‘#’ symbol in front of “Logger Configuration” is a comment marker. Anything on a line after the “#” symbol will be ignored, so this is a good way to make notes about what a section does, or to disable a setting without deleting it.

And that’s it

Well… almost. Now that you’ve changed the configuration file, save it, and then close and restart the MTConnect Agent.

Now the agent should be running using your new settings. Verify that it’s running, that it loaded your new Devices file, and that it’s seeing data from the MTConnect adapters, and you’re golden.

But if you do run into problems, remember that there are plenty of resources for troubleshooting. If you’re not sure where to start, try the MTConnect User Forum to ask questions of a community knowledgeable about all things MTConnect.

[EDIT: as of 2020, the MTConnect User Forum is no longer active. Try checking StackOverflow for MTConnect-related questions and answers. Or if you message me your question, I’ll try to answer it or direct you to an appropriate resource.]

14 thoughts on “Install the MTConnect Agent In Two Easy-ish Steps

  1. Thanks man, your post is gold, I’ve been searching for a proper tutorial on how to implement mtconnect but resulted in vain. Quick question/ suggestion, please make a tutorial on how to run the adapter and how to extend it for new model of fanuc(the current one has for 0i d and 30i series) but i’m looking for 0i mf series.

  2. Hi, really interesting stuff. Been trying to implement this in one of the machines (Doosan-Fanuc) but I am stuck at one point. I have contacted Fanuc and they provided me some focus libraries for the adapter. Do you have any info or guide me on how I can use these libraries to make an adapter and follow this tutorial for the full implementation?


    1. Check the MTConnect adapter repository on GitHub: One of the included adapters is for Fanuc (using the Fwlib32 Focas library, which is probably what Fanuc sent you).

      Unfortunately the repository is not well-documented. If you’re unable to get it working, send me a follow-up question and I might be able to help.

      1. Thanks for the reply. I did use the github link you suggested and following this “

        ; to compile. I am in the last step where I am getting an error “lfwlib32 not found”. Do you have any info regarding this?

        1. Thanks for the reply. I did use the github link you suggested and following this “; to compile. I am in the last step where I am getting an error “lfwlib32 not found”. Do you have any info regarding this?
          /usr/bin/ld: skipping incompatible //usr/local/lib/ when searching for -lfwlib32
          /usr/bin/ld: cannot find -lfwlib32

          1. Based on the error message, the linker cannot link the library, but it is present.

            Since this is a 32-bit library, I recommend checking your compiler settings to verify that you’re targeting 32-bit (x86) architecture.

    1. The data from the agent will be XML. You may be able to find an XML-to-CSV converter to transform it and output to a file.

  3. Thank you for the article. I’m running the MTConnect agent on my computer right now, but I can’t find a way to restart it. The “service name” at the top of the config file should be the name of the service in Services right? It doesn’t show up, yet I am seeing the agent’s output live on localhost:5000. Very odd. Any ideas?

    1. How did you install the agent? I downloaded the latest installer for Windows, modified the “ServiceName” at the top of the config file, and then ran “agent.exe install agent.cfg”. After this, I could see the agent with the custom name in both the services.msc service control panel, and from running “net start”.

  4. Hi, thanks for your explanation. Everything is running well. I can also go to “localhost:5000” but when I try to see the incoming data by entering “localhost:5000/Current” I get the error “Error processing request from: – No matching route for: GET /Current.
    Anything I forgot to adjust?

Leave a Reply

Your email address will not be published. Required fields are marked *

%d bloggers like this: