Connect your data with your AI assistant

Set it up

You need a Windows or Linux machine, an assistant that runs local MCP servers (below), and a Kymoscope account; a free one is enough to start.

The shortest way: if your assistant can run commands, as Claude Code, Cursor and VS Code with Copilot can, say "Install the Kymoscope MCP following https://kymoscope.com/docs/mcp". It follows the next section and asks before it installs anything. On Claude Desktop, use the extension, under Add it to your assistant. To do it yourself:

1. Install uv, the small program that fetches and starts the server (Claude Desktop's extension doesn't need it). In a terminal:

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Add the server to your assistant, as the next section shows.
3. Quit your assistant completely and start it again. It only reads this setting when it starts.
4. Say: "Connect my data to Kymoscope." Your assistant leads from there, one step at a time.

If nothing happens, or your assistant says the server failed, see If the server won't start.

For AI assistants: install it for the person

For an AI assistant that a person asked to install this server. Work in their terminal, as their own account, show each command before you run it, and add the server only to the client you are running in. Claude Desktop can't run these commands: tell the person to install the extension, under Add it to your assistant.

1. Check the system: Windows or Linux. On macOS, stop and tell the person it isn't supported.
2. Find uvx: run uvx --version. If that fails but ~/.local/bin/uvx exists (Windows: %USERPROFILE%\.local\bin\uvx.exe), uv is installed and this terminal started before it: use that full path in place of uvx below, in Windows form on Windows (C:\Users\<name>\.local\bin\uvx.exe).
3. If there is no uv, ask the person first, then run the official installer. It installs for this account only, needs no administrator, and puts uvx in that same folder, so use the full path as above:

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

   curl -LsSf https://astral.sh/uv/install.sh | sh

4. Add the server to your own client:
   • Claude Code: it prints Added .... Then claude mcp get kymoscope shows whether it connects.

     claude mcp add --transport stdio --scope user kymoscope -- uvx --no-config --python 3.12 kymoscope-mcp

   • Cursor: add the kymoscope entry to mcpServers in ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json). Create the file if it's missing; keep every other server in it.

     {
       "mcpServers": {
         "kymoscope": {
           "type": "stdio",
           "command": "uvx",
           "args": ["--no-config", "--python", "3.12", "kymoscope-mcp"]
         }
       }
     }

   • VS Code with Copilot: it prints Added MCP servers: kymoscope and writes the user mcp.json (%APPDATA%\Code\User\mcp.json, or ~/.config/Code/User/mcp.json on Linux). From bash:

     code --add-mcp '{"name":"kymoscope","type":"stdio","command":"uvx","args":["--no-config","--python","3.12","kymoscope-mcp"]}'

     From Windows PowerShell 5.1, which drops plain quotes (if it answers Invalid JSON, use the other form):

     code --add-mcp '{\"name\":\"kymoscope\",\"type\":\"stdio\",\"command\":\"uvx\",\"args\":[\"--no-config\",\"--python\",\"3.12\",\"kymoscope-mcp\"]}'

   With a full path to uvx, put it in place of uvx; in JSON, write each backslash twice.
5. Ask the person to quit the client completely and start it again (Claude Code: a new session). The first start downloads the server, which can take a minute.
6. Check: the Kymoscope tools are listed, get_started among them. Call get_started; it leads from there. With no tools after a minute, see If the server won't start.

Don't:

• use an administrator or sudo terminal, or install uv any other way (pip, a package manager);
• drop --no-config or --python 3.12, or add an env or --env the person's IT didn't ask for;
• ask for an API key or let the person paste one in the chat: get_started says where it goes.

Add it to your assistant

Claude Code

Run this once in a terminal. --scope user makes it available in all your projects:

claude mcp add --transport stdio --scope user kymoscope -- uvx --no-config --python 3.12 kymoscope-mcp

Claude Desktop

The Kymoscope extension installs it with a click and needs no uv: Claude Desktop fetches what it needs. Download kymoscope-mcp.mcpb, then open it by double-clicking it, dragging it onto the Claude window, or in Settings, Extensions, Advanced settings, Install Extension, then choose Install. Claude Desktop says it isn't signed. The first install can take a few minutes.

Without the extension, open Settings, then Developer, then Edit Config. That opens %APPDATA%\Claude\claude_desktop_config.json on Windows, or ~/.config/Claude/claude_desktop_config.json on Linux, where Claude Desktop is in beta. Installed from the Microsoft Store, current versions keep it at %LOCALAPPDATA%\Claude-Data\claude_<id>\claude_desktop_config.jsoninstead. Edit Config opens the right file, whichever it is. If the file already has an mcpServers section, add only the kymoscope entry to it. Quit from the system tray too: closing the window doesn't restart it.

{
  "mcpServers": {
    "kymoscope": {
      "command": "uvx",
      "args": ["--no-config", "--python", "3.12", "kymoscope-mcp"]
    }
  }
}

Cursor

Create ~/.cursor/mcp.json (on Windows, %USERPROFILE%\.cursor\mcp.json) to have it everywhere, or .cursor/mcp.json in one project:

{
  "mcpServers": {
    "kymoscope": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--no-config", "--python", "3.12", "kymoscope-mcp"]
    }
  }
}

VS Code with GitHub Copilot

VS Code's format differs: the top key is servers, and type is required. Open the Command Palette (Ctrl+Shift+P), run MCP: Open User Configuration, and save this. VS Code asks you to trust the server when it first starts it. Use Copilot Chat in agent mode.

{
  "servers": {
    "kymoscope": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--no-config", "--python", "3.12", "kymoscope-mcp"]
    }
  }
}

If it says it has no Kymoscope tools

The server downloads what it needs the first time it starts, which can take a minute, and an assistant may answer before that ends. Ask it again: from then on the server starts in seconds.

If it says it can't find uvx

A desktop app doesn't always see the programs a terminal sees. Find the full path with where.exe uvx on Windows or which uvx on Linux. If it finds nothing, close the terminal, open a new one and try again. Put the path in command. In JSON, each backslash is written twice. Then restart the assistant.

{
  "mcpServers": {
    "kymoscope": {
      "command": "C:\\Users\\you\\.local\\bin\\uvx.exe",
      "args": ["--no-config", "--python", "3.12", "kymoscope-mcp"]
    }
  }
}

What your assistant will walk you through

1. On Windows, an administrator lock of the folder, once (next section).
2. Your API key. Create one at app.kymoscope.com/account under API & Real-time streaming, or in a project's API keys tab. Save the whole key, alone, in api_key.txt in the folder your assistant names. Your assistant gives you the command that opens it: on Windows, press Windows+R and run notepad C:\ProgramData\Kymoscope\api_key.txt, answer Yes to create the file, paste the key, save and close. C:\ProgramData is a hidden folder, so File Explorer doesn't show it; the command opens the file directly. Never paste it in the chat: what's in the chat reaches your AI provider.
3. Where your data is. It checks this machine reaches the system, picks a source type, and names the stream after the source; what you don't know, it looks up. If it would connect to your system unencrypted, the preview says so, and it tells you why. Ask the system's owner for a read-only user; a password goes in a file too, never in the chat.
4. Your tags. It asks your system which tags it offers and writes them to tags.csv in the folder, after your yes. For OPC UA it first asks the server which security it offers and proposes the strongest; if the server offers none, it tells you so plainly before anything connects unencrypted.
5. A test that reads for a few seconds and sends nothing, then a short real send to your account. The stream leaves LIVE within about a minute of the send ending: nothing is wrong, and you see it live once the service runs.
6. The service, so the collector keeps running after a restart. You or IT run the administrator commands it hands you. Nothing else needs an administrator console: listing the tags doesn't.
7. Your own eyes. Open Kymoscope, click LIVE on the left and Connect beside the stream's name (on a new account, skip the tutorial and its demo first). To see values: Charts, Multi-Series, right-click the new chart, Multiband settings, Add signal. Check that the channels look right. That's the final proof.

On Windows: lock the folder, then save the key

The first thing your assistant gives you is a set of commands for an administrator Command Prompt (cmd, not PowerShell). To open it: press Start, type cmd, right-click Command Prompt, and choose Run as administrator. Run the commands exactly, once, and tell your assistant. If you have no administrator account, forward them to IT.

The lock comes first because the collector's service runs as SYSTEM from C:\ProgramData\Kymoscope, so any account able to write there could take over the machine, and the lock moves aside whatever was in the folder, your key included. If you installed the collector earlier, your assistant first says what it found and what replacing it means: the service stops and is removed, live data stops until the new install is done, data not yet sent from the old folder isn't sent, and your account, streams and history online stay as they are.

• A key saved before the lock could have been read by other accounts. Replace it: Reissue in the project's API keys tab, or for a personal key revoke it and create a new one. Save the new one in the locked folder.
• What was there moves to a folder named C:\ProgramData\Kymoscope.untrusted-…. Don't reuse anything from it. Delete it with the rmdir /S /Q line your assistant gave you. If nothing was there, there's nothing to delete.

Linux has no lock step. You get two sudo commands that create /opt/kymoscope for your account.

What approving looks like

Before any change, your assistant shows a plain sentence saying what will happen, with the details under it, and asks you. Only your yes lets it go on, and that yes covers exactly what was shown: if anything differs, you get a new preview. Reading and checking need no yes.

Your assistant also has its own prompts, asking to allow a tool. Expect one for test_source: it sends nothing, but it runs the connector's code and reads from your system, so it isn't a read-only tool.

When something fails, your assistant tells you what happened, the next step and who does it: you, IT, a project lead, a project member, the account owner or the source system's owner.

When the data is on another server

If this machine can't reach your system, your assistant prepares a zip. Copy it to a server that can, save the API key next to the install script, and run the script as its INSTALL.md says. It tests each source first and starts nothing if a test fails. That server needs Python 3.10 to 3.13 and access to a package index. From this machine, your assistant can then see the collector is alive, not that data flows: you confirm the channels in Kymoscope.

• In the zip: the configuration without its comments, connector code, files the sources need such as tag lists and certificates, the install scripts, and each file's hash.
• Never in the zip: the API key, secret files and private keys, state, backups, logs and anything hidden. You bring those to the server. Secrets are recognised by name and shape, so read the preview's configuration and any connector code before sending it anywhere.

Connectors your assistant writes, and who supports what

When no built-in source fits, your assistant writes a connector: a readable folder under connectors/, with a README saying what it reads. It's yours, so keep it in your own version control. Kymoscope supports the collector, the connector contract and this server, not the generated code. Your assistant can diagnose and fix it with the same tools.

If the collector was updated by hand or by IT, ask your assistant to test the source again. If a connector that passed on an earlier version now fails, it says so (adapter_failed_after_update); earlier versions of the connector stay in backups.

Members and account deletion are yours, at your account. To change plan, the account owner uses Talk to us on the pricing page.

If the server won't start

For IT. Before the server starts there's no tool to explain anything, so the assistant only reports that it failed. To see why, run uvx --no-config --python 3.12 kymoscope-mcp in a terminal as the same user: a server that started says nothing and waits, so stop it with Ctrl+C. Claude Desktop keeps the same output in %APPDATA%\Claude\logs\mcp-server-kymoscope.log; Cursor shows it in the Output panel under MCP Logs.

Settings go in the assistant's env

A desktop app doesn't read what you set in a terminal, so settings go in the env of the server's entry. Keep only the lines you need. VS Code takes the same env under servers; Claude Code takes --env NAME=value before --transport.

{
  "mcpServers": {
    "kymoscope": {
      "command": "uvx",
      "args": ["--no-config", "--python", "3.12", "kymoscope-mcp"],
      "env": {
        "UV_SYSTEM_CERTS": "true",
        "UV_DEFAULT_INDEX": "https://mirror.customer.local/simple",
        "HTTPS_PROXY": "http://proxy.customer.local:8080"
      }
    }
  }
}

• A company mirror works only through UV_DEFAULT_INDEX. --no-config makes uvx ignore every uv.toml, as any Windows user can write the system-level one and it would choose the package this server is installed from. The server gives uv the same rule when it installs the collector.
• --python 3.12 keeps uv off a Python newer than the server's parts support. uv uses a 3.12 already on the machine, or downloads its own.
• A password in a mirror or proxy URL stays in plain text in this file. Prefer a mirror and proxy that need none here.
• HTTPS_PROXY covers the server and its installs. The running collector has its own proxy setting; see Proxy.

Application control

WDAC and AppLocker can block what the server needs. uv's own programs and the Python from python.org are signed. The programs uv creates to start the server and collector aren't, and the packages from PyPI hold native files, so expect to allow them: pydantic_core, rpds, yaml, charset_normalizer, _cffi_backend, cryptography, pywin32 (the collector's service host too), and each source type's own libraries. A Python that uv downloads is another program to allow, so install Python 3.12 from python.org for all users instead.

Allow these by path, or by hash for files that change with each release. A path rule on a folder its user can write also lets anything that user puts there run, so your security team decides on the first two; UV_CACHE_DIR in env moves the cache elsewhere if that helps. Smart App Control takes no rules at all. Where no rule is acceptable, use one of these:

• WSL: install uv inside it, then point the assistant there, as below. It works as on Linux: /opt/kymoscope, and the service needs systemd in WSL.
• Docker: this server has no image, but the collector does: follow the collector guide. Prepare its configuration with this server on a machine allowed to run it, or by hand.

{
  "mcpServers": {
    "kymoscope": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "--", "bash", "-lc", "uvx --no-config --python 3.12 kymoscope-mcp"]
    }
  }
}

Security: what runs, and what your AI provider sees

For the security reviewer.

What runs where

• The server runs on this machine, started by the assistant as the signed-in user. It has no cloud side. It calls Kymoscope only to check the API key and a stream's last-seen time.
• Data goes from the collector to Kymoscope end-to-end encrypted, as in the collector guide. It doesn't pass through the server.
• Administrator rights are never taken. Without them, the server returns the exact commands. An assistant already started as administrator can apply them itself, after a yes.
• The server's version: uvx takes what the index offers. To pin it, write kymoscope-mcp==<version> in the entry.

What your AI provider sees

Whatever a tool returns goes to your AI provider, as does the chat. Choose your provider with that in mind.

• Normally: tag names, source addresses, counts and time ranges, this machine's name, your account name, folders, stream names, what your plan includes, connector code, the configuration with secrets masked, a failed install's output, and log lines reduced to their time, level, logger and a code or exception type, or to a sentence of ours for a routine start-up warning and for how the collector last stopped. A refusal from Kymoscope itself comes back whole.
• Real readings, normally: each tag's lowest and highest value in a test, with its first and last time and count. For a steady signal, these are the value itself.
• More only with the samples option: a few values per tag and every exception's message. Your assistant is told to ask you first, but the server can't check that it did. Messages about the system, such as a failed connection to an address or a missing file, come back without it.
• The server can't limit an assistant's other tools. One that can read files, as Claude Code and Cursor can, can open collector.log, the configuration or a key file like any program of that user. Set its permissions accordingly.

Secrets, previews and logs

• The API key and passwords live in files or environment variables. Tools never return them, and they refuse a plain password in the configuration or in connector code. They recognise secrets by name and shape, so one with neither can get through.
• A configuration preview shows only what changes, with secrets masked. Its confirm code covers the file as it was and as it would be, so any other edit to the file asks for a new yes.
• diagnose holds codes, exception types and those fixed sentences, with the full text only in collector.log on this machine. It doesn't load the configuration, as that runs connector code; test_source(offline=True) does.
• The previous configuration and connector files stay in backups, and every change goes to mcp-actions.log.

The yes is a safeguard, not a boundary

A server can't tell a person's yes from an assistant answering itself or a client set to auto-approve, so tools are also marked as writes for the client's own prompts. Setting KYMOSCOPE_MCP_CONFIRM=off in env skips the question: changes apply at once with no preview, and results and the log say confirmation: off.

Code and permissions

• Generated connectors run with the collector's permissions, at every configuration load and test: the permissions of whoever starts it, and in the service, its account. The test is a review aid, not isolation. Read adapter.py if your policy requires it. The preview gives your assistant the whole file, so ask to see it.
• On Windows, whoever can write the folder acts as SYSTEM, as the service runs its code. The lock leaves LocalSystem, Administrators and the account that set it up, so that account and any assistant it runs have that power. On Linux the service runs as the unprivileged kymoscope user.
• Use a read-only user on your system. The connector contract tells code never to write to the source; only the source's own permissions can ensure it.