Installing the Hevo Plugin in Claude Code

Last updated on Nov 18, 2026

The Hevo plugin adds the Hevo MCP server to Claude Code, so you do not need to add the server to the settings of Claude Code yourself. Along with the server, the plugin installs the hevo-pipelines skill, which gives Claude Code instructions for using the tools of the server, such as the steps to find the cause of a failure and the safety rules for changes. Read Components for more information.

When Claude Code starts, the plugin starts the server on your machine, and the server reads your API credentials from a key file.


Prerequisites


Saving your API Credentials

The server looks for your API credentials in a key file named hevo-key.json, in the .hevo folder of your home directory, such as ~/.hevo on macOS and Linux, or C:\Users\<your user name>\.hevo on Windows. Save the file that you downloaded when you generated your API credentials as this key file. The file that you download from Hevo is already named hevo-key.json. Hevo shows the Secret Key only once, so if you did not download or copy it, generate a new pair of API credentials.

Perform the following steps to save your API credentials:

  1. Run the following commands in a terminal to create the .hevo folder and move the downloaded file into it as hevo-key.json:

    mkdir -p ~/.hevo
    mv "<path to the downloaded file>" ~/.hevo/hevo-key.json
    

    On Windows, run the following commands in PowerShell instead:

    New-Item -ItemType Directory -Force "$HOME\.hevo" | Out-Null
    Move-Item "<path to the downloaded file>" "$HOME\.hevo\hevo-key.json"
    

    If you copied the Access Key and Secret Key instead of downloading them, run only the command that creates the .hevo folder. Then, create the hevo-key.json file in the folder in a text editor, with the following content, and save it as plain text, without a .txt extension:

    {
      "access_key": "<your Access Key>",
      "secret_key": "<your Secret Key>"
    }
    
  2. Run the following command to allow only you to read the file:

    chmod 600 ~/.hevo/hevo-key.json
    

    On Windows, run the following commands in PowerShell instead. They allow only you to access the .hevo folder and the key file:

    icacls "$HOME\.hevo" /inheritance:r /grant:r "${env:USERNAME}:(OI)(CI)F"
    icacls "$HOME\.hevo\hevo-key.json" /inheritance:r /grant:r "${env:USERNAME}:F"
    

    On macOS and Linux, the server does not use a key file that other users on the machine can read. On Windows, the server does not check who can read the file, so these commands prevent other users from reading your API credentials.

Do not paste your API credentials into a conversation with your agent. If you paste them by mistake, generate a new pair of API credentials and delete the existing pair. Read Rotating your API Credentials for the steps.

Your API credentials are now saved in the key file, and you can install the plugin.


Installing the Plugin

The plugin is installed from the Hevo plugin marketplace, which you add to Claude Code once.

Perform the following steps to install the plugin:

  1. Start Claude Code.

  2. Run the following commands in Claude Code to add the Hevo plugin marketplace and install the plugin:

    /plugin marketplace add hevoio/hevo-mcp
    /plugin install hevo-data@hevo-data
    
  3. Exit Claude Code, and start a new Claude Code session.

To check that the plugin is installed, run the claude plugin list command in a terminal. The list shows hevo-data@hevo-data with the status enabled.

Claude Code uses the hevo-pipelines skill when you ask about Hevo. To run the skill yourself, use the /hevo-data:hevo-pipelines command. The first time the agent calls each Hevo tool, Claude Code asks for your permission to use it. This permission is separate from the approval prompts of the server.

After you install the plugin, Claude Code can connect to Hevo.


Verifying the Connection

The agent needs your account region, which is the subdomain in the URL of your Hevo account, such as us in us.hevodata.com. If you do not name the region in your request, the agent asks you for it, and then names it in every request to Hevo. Read Identifying your Region to find your account region.

Note: The eu2 region has only Edge Pipelines, and the us-gcp region has only Standard Pipelines. In these regions, the agent can work only with the type of Pipeline that is available in the region.

Ask Claude Code to run hevo_whoami for region us, replacing us with your account region. The agent calls the hevo_whoami tool and reports the following details:

  • The region of the check.

  • The key file from which the server read your API credentials.

  • The result of checking your API credentials with the Hevo API for Edge Pipelines, Standard Pipelines, and team users. In the eu2 and us-gcp regions, the check reports the type of Pipeline that is not available in the region as not offered. If the role of the user who generated your API credentials does not allow an action, the check for that action fails, such as the check for team users.

  • The changes that the agent is allowed to make.

  • The folder from which the server reads your secret files.

  • The version of the server, and whether a newer version is available.

  • The result of checking the installed components against the versions with which the release was tested.

  • The fingerprint of the tools that the server provides.

If the check fails, the agent reports the reason. Do the following based on the reason:

  • The server cannot find your API credentials: Check that your key file is named hevo-key.json and is in the .hevo folder of your home directory.

  • The key file does not contain an Access Key and a Secret Key: Save the file that you downloaded from Hevo without changes, or create the file with the content in the Saving your API Credentials section.

  • Hevo rejects your API credentials: Check that the Access Key and the Secret Key are correct and not deleted. For teams created before Release 2.00, API credentials work only in the region in which you generated them, so check that you specified that region.

  • The server does not use your key file because other users can read it: Run the chmod 600 command in the Saving your API Credentials section.

  • The server does not use your key file because it is a symbolic link: Delete the link from the .hevo folder, and move or copy the key file itself into the folder. A symbolic link is a shortcut that points to a file in another folder.

If Claude Code does not list any Hevo tools, check that uv is installed and that the uvx command runs in a new terminal. Then, exit Claude Code, and start it again from a new terminal.

When the check succeeds, the agent can view your Hevo account, but cannot change anything until you allow changes. Read Allowing and Approving Changes by your Agent to allow the agent to make changes.


Updating the Plugin

The hevo_whoami tool reports when a newer version of the server is available. To update the plugin automatically, turn on auto-update for the Hevo plugin marketplace in Claude Code. To update it yourself, run the following commands in a terminal:

claude plugin marketplace update hevo-data
claude plugin update hevo-data@hevo-data

After you run these commands, exit Claude Code, and start a new Claude Code session. The agent then uses the new version of the server.


Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Nov-18-2026 2.54 New document.

Tell us what went wrong