Ask an AI assistant about your own tags
“What has the boiler temperature been doing today?” “Are there any active alarms?” — answered from your own account, not from the assistant's general knowledge. This is an MCP server for Claude Desktop and any MCP-compatible host, and it wraps the same read API everything else on this site uses.
Read-only by default, as a decision rather than an accident: the write tools do not exist as far as the assistant is concerned until you explicitly enable them. Installed from our public git repository — not yet on PyPI, and this page says so rather than letting you pip-install something that is not ours.
Last updated
1. Get an API key
Create an account and an API key first. The free plan is €0 and takes an email address — no card — and gives you 5 tags and 50,000 readings a day. Then create the key on the Settings page in Tag Historian Explorer — and the scope you give it is not a detail.
The key is shown once. Copy it straight into the env block of your MCP host’s config — if you lose it, generate a new one rather than hunting for the old one.
2. Install the server
Neither this package nor the taghistorian client it wraps is on PyPI yet, so both install from a checkout of the public repository:
git clone https://github.com/softi-dev/tag-historian-clients.git
cd tag-historian-clients
python -m venv .venv
.venv/bin/pip install -e python-client # the client library the server wraps
.venv/bin/pip install -e mcp-server # the server itself- Order matters. Install
python-clientfirst —mcp-serverdeliberately does not pull it from the network, and skipping the first line makes the server fail fast at startup with a one-line message saying to run it. - Python 3.10 or newer. On Windows the pip path is
.venv\Scripts\piprather than.venv/bin/pip.
3. Point Claude Desktop at it
Add an entry to your host's MCP server config — for Claude Desktop that is claude_desktop_config.json:
{
"mcpServers": {
"taghistorian": {
"command": "/absolute/path/to/tag-historian-clients/.venv/bin/taghistorian-mcp",
"env": {
"TAGHISTORIAN_API_KEY": "your-api-key-here"
}
}
}
}taghistorian-mcp is the console script the install above puts in the virtualenv — the host launches it as a local subprocess and talks to it over stdio; you never run it by hand. On Windows the command is ...\.venv\Scripts\taghistorian-mcp.exe.
What you can ask
Six read tools, always available. In the assistant they look like questions, not tool names:
| What you ask | What answers it |
|---|---|
| “List all my tags in the boiler area.” | list_tags — your tag list, names and metadata |
| “What did the flow do between 09:00 and 10:00?” | read_measurements — stored readings over a time range |
| “What is the current value of tank_1.level?” | read_last_value — the latest stored reading |
| “What has the boiler temperature been doing this month?” | read_aggregated — min, max, average, sum or count, bucketed by any interval you choose (10 minutes by default) |
| “Are there any active alarms right now?” | list_active_alerts — alarms currently firing |
| “Which alert rules do I have, and which are disabled?” | list_alert_rules — the rules as configured |
None of these can change anything in your account, and they stay available regardless of the write gate below.
The write gate
Setting TAGHISTORIAN_ENABLE_WRITE to a truthy value — 1, true or yes, case-insensitive; anything else, including an empty string, leaves it off — registers three more tools: write_measurement, write_batch_measurements and create_tag. Enabling them means the key in the config needs Scope Write rather than Read — except for create_tag, which needs Admin, the same as creating a tag anywhere else in the product. A Write key gets a 403 on that one call specifically; the other two work with it.
- Off means absent, not refused. While the gate is off, the write tools are not in
tools/listat all — the assistant cannot see them, so there is nothing for it to try. There is no “ask before writing” middle ground: the setting is decided once, at startup, by whoever configures the environment. - The server announces its mode. Whichever way the gate is set, it logs the mode loudly to stderr on startup, so your MCP host's server log says which one you got.
Common questions
- What can the AI assistant actually do with my account?
- By default, read only. Six tools: list your tags, read stored history for a tag, read its latest value, read bucketed summaries over any interval, list active alarms, and list your alert rules — including which ones are disabled. None of them can change anything. The three write tools exist in the package but are not even registered until you set TAGHISTORIAN_ENABLE_WRITE.
- Can it write to my account?
- Not unless you explicitly turn that on. Setting TAGHISTORIAN_ENABLE_WRITE to 1, true or yes — anything else, including an empty string, leaves it off — registers write_measurement, write_batch_measurements and create_tag. Those are real, billable writes: the first two store real measurement values in your history, and create_tag registers a tag that counts against your plan’s tag quota. While the gate is off the write tools do not appear in the assistant’s tool list at all, and the setting is decided once, at startup, by whoever configures the environment — not by the model, and not per call.
- What scope should the API key have?
- Read. Set Scope to Read when you create the key — everything the server does by default only reads, and a key that cannot write is the right thing to leave sitting in a config file. If you enable the write tools, a Write-scope key covers write_measurement and write_batch_measurements; create_tag needs Admin, the same as creating a tag anywhere else in the product, so even a Write key gets a 403 on that one call. Whichever tool gets refused, the error comes back to the assistant as a clear message rather than a crash.
- Is it on PyPI?
- Not yet — neither taghistorian-mcp nor the taghistorian client it wraps. Until it is, install both from a checkout of our public repository, github.com/softi-dev/tag-historian-clients: two pip install -e steps, in that order. The install section above has the exact commands.
- Which AI assistants work with it?
- Any MCP host that can launch a local stdio server — Claude Desktop is the one documented here, and the config shape is the same idea elsewhere. The server itself runs on your machine as a subprocess of the host and talks straight to the Tag Historian API with your own key. What the tools return becomes part of your conversation with the assistant, so it is shared with whichever host you connected it to.