Factry Historian MCP Server

This guide walks you through installing and running the Factry Historian MCP Server.

What is this?

The Factry Historian MCP Server is a bridge that lets AI assistants (such as Claude) talk to your Factry Historian instance. It exposes Historian data such as assets, measurements, event as tools an AI can call.

Prerequisites

Before you start, make sure you have the following:

A running Factry Historian instance

The MCP server connects to Factry Historian API. You need:

The API URL of your Factry Historian instance (e.g. `http://localhost:8000/api`)

An API token, a token with access to Factry Historian. Obtaining an API token

Your Organization UUID, visible in the Historian web interface under organization settings. OrganizationsOrganizations

Docker

Docker is the software that runs containers. Install it from the official Docker website:

Mac / Windows: Install Docker Desktop

Linux: Follow the Docker Engine install guide for your distribution

To verify Docker is installed, open a terminal and run:

docker --version

You should see output like Docker version 27.x.x.

Installation

Using Docker

No binary installation is needed. The MCP server is available as a pre-built image on Docker Hub: factry/mcp-server.

The recommended way to connect an AI assistant to the MCP server is via stdio transport. Claude Desktop (or another MCP client) launches the container directly and communicates with it over stdin/stdout. This means no port needs to be opened and no separate server process needs to stay running.

For a custom LLM application or web-based AI platform that connects over HTTP instead, see Factry Historian MCP Server (HTTP mode).

Connecting Claude Desktop

Edit your Claude Desktop configuration file. Its location depends on your operating system:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add the following entry under mcpServers:

{
  "mcpServers": {
    "factry-historian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "FACTRY_HISTORIAN_API_URL",
        "-e", "FACTRY_HISTORIAN_API_TOKEN",
        "-e", "FACTRY_HISTORIAN_ORGANIZATION_UUID",
        "factry/mcp-server:latest"
      ],
      "env": {
        "FACTRY_HISTORIAN_API_URL": "http://host.docker.internal:8000/api",
        "FACTRY_HISTORIAN_API_TOKEN": "your-token-here",
        "FACTRY_HISTORIAN_ORGANIZATION_UUID": "your-organization-uuid-here"
      }
    }
  }
}

Replace the values in env with your actual Historian URL, token, and organization UUID.

host.docker.internal is a special hostname that Docker resolves to your host machine's IP address on linux and windows machines. Use it when Historian is running locally on the same machine. If Historian is running on a different host, replace it with that host's address.

On Linux, host.docker.internal requires adding --add-host=host.docker.internal:host-gateway to the args list.

After saving the file, fully quit and restart Claude Desktop. Open a new conversation and ask something like "What assets are available in Historian?" to verify the connection.

Optional: Grafana integration

If you also have Grafana, add the following to the env block to enable Grafana-related tools:

"GRAFANA_URL": "http://host.docker.internal:3000",
"GRAFANA_API_KEY": "your-grafana-service-account-token"

Configuration reference

All configuration is done through environment variables.

Variable	Required	Default	Description
FACTRY_HISTORIAN_API_URL	Yes	None	URL to your Factry Historian API
FACTRY_HISTORIAN_API_TOKEN	Yes	None	Token for authenticating with Historian
FACTRY_HISTORIAN_ORGANIZATION_UUID	Yes	None	UUID of the organization in Historian
GRAFANA_URL	No	None	URL to your Grafana instance (enables Grafana tools)
GRAFANA_API_KEY	No	None	Grafana service account token
LOG_LEVEL	No	info	Log verbosity: debug, info, warn, error
STATISTICS_DISABLED	No	false	Set to true to disable anonymous usage statistics

Troubleshooting

The tools do not appear in Claude Desktop

Fully quit Claude Desktop (not just close the window) and restart it, configuration changes require a full restart.

Check the Claude Desktop logs for errors: ~/Library/Logs/Claude/mcp*.log on macOS, %APPDATA%\Claude\logs on Windows.

Confirm Docker is running and that docker run --rm -i factry/mcp-server:latest does not produce an error on its own.

The MCP server cannot reach Historian

If Historian is running locally, make sure you are using http://host.docker.internal:8000/api and not http://localhost:8000/api. Inside a Docker container, localhost refers to the container itself, not your machine.

On Linux, add "--add-host=host.docker.internal:host-gateway" to the args list in your Claude Desktop config.

The container exits immediately

Run the container manually to see the error output:

docker run --rm -i \
  -e FACTRY_HISTORIAN_API_URL=http://host.docker.internal:8000/api \
  -e FACTRY_HISTORIAN_API_TOKEN=your-token \
  -e FACTRY_HISTORIAN_ORGANIZATION_UUID=your-uuid \
  factry/mcp-server:latest