--- title: Factry Historian MCP Server slug: how-tos/Hf-a-mcp docTags: createdAt: 2026-03-30T09:12:57.007Z --- 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](docId:-VR6PRLDWhuLaWeKLZWoL) - Your **Organization UUID,** visible in the Historian web interface under organization settings. [Organizations](docId\:ODmaDpIfQLvqBpGFarnXi) **Docker** Docker is the software that runs containers. Install it from the official Docker website: - **Mac / Windows:** Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) - **Linux:** Follow the [Docker Engine install guide](https://docs.docker.com/engine/install/) for your distribution To verify Docker is installed, open a terminal and run: ```bash 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](https://hub.docker.com/r/factry/mcp-server/tags). 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)](docId\:meTSsZcQeFUdbdqUjhS6V). ### 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`: ```json { "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. :::hint{type="info"} `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: ```json "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: ```bash 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 ```