Adding the Hevo MCP Server to Claude Desktop

Last updated on Nov 18, 2026

You can add the Hevo MCP server to Claude Desktop from the hevo-mcp package on PyPI. Claude Desktop then starts the server on your machine and communicates with it directly, so the server needs no port or URL. The server reads your API credentials from a key file.

Claude Desktop starts the server with the following command:

uvx --from hevo-mcp==1.0.0 -c https://raw.githubusercontent.com/hevoio/hevo-mcp/v1.0.0/constraints.txt --python 3.12 hevo-mcp

The command installs version 1.0.0 of the hevo-mcp package, along with the exact versions of the components with which that release was tested, and starts the server with Python 3.12. Keep the --python 3.12 option in the command, as the release is tested only with Python 3.12. Without it, uv may use a newer version of Python, and installing the server can then need the Microsoft C++ Build Tools. If your network blocks raw.githubusercontent.com, use the uvx --python 3.12 hevo-mcp==1.0.0 command instead. In the settings of Claude Desktop, the args value is then ["--python", "3.12", "hevo-mcp==1.0.0"]. This command installs the same version of the server with the latest compatible components, and the hevo_whoami tool then lists the components that differ from the tested versions.

Note: Claude Desktop cannot show approval prompts, so the agent cannot make the changes that need your approval, such as a delete or a configuration change. Read Approval Prompts in each Agent for more information.


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 add the server to Claude Desktop.


Adding the Server to Claude Desktop

Claude Desktop does not use the PATH of your shell, so you must specify the full path of the uvx command in its settings.

Perform the following steps to add the server:

  1. Run the following command to find the full path of the uvx command:

    which uvx
    

    On Windows, run the where.exe uvx command in PowerShell instead.

  2. Add the following entry to the claude_desktop_config.json file, which is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows. If the file does not exist, create it. Replace <path of uvx> with the path from step 1. On Windows, write each backslash in the path twice, such as C:\\Users\\<your user name>\\.local\\bin\\uvx.exe:

    {
      "mcpServers": {
        "hevo": {
          "command": "<path of uvx>",
          "args": ["--from", "hevo-mcp==1.0.0",
                   "-c", "https://raw.githubusercontent.com/hevoio/hevo-mcp/v1.0.0/constraints.txt",
                   "--python", "3.12", "hevo-mcp"]
        }
      }
    }
    

    If the file already exists, keep its content, and add the mcpServers key next to the existing keys. To find the file, in Claude Desktop, click Settings, and then click Developer. Then, click Edit config. If the file already contains an mcpServers object, add only the hevo entry to it.

  3. Quit Claude Desktop, and open it again.

After you open Claude Desktop again, the Hevo MCP server is available in it. The first time the agent calls each Hevo tool, Claude Desktop asks for your permission to use it. This permission is separate from the approval prompts of the server.


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 Desktop 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 Desktop does not list any Hevo tools, check that uv is installed and that command contains the full path of the uvx command. Then, quit Claude Desktop, and open it again.

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 the changes that do not need approval.


Using the Skill

The hevo-pipelines skill helps the agent use the tools of the server correctly. Claude Desktop does not use the Hevo plugin, so the skill is not installed. The server sends the key rules of the skill to Claude Desktop when it connects, and provides the full skill as the skill://hevo-pipelines/SKILL.md resource. Read Resources for more information.


Updating the Server

The hevo_whoami tool reports when a newer version of the server is available. To update the server, change the version in the following places in the args value: hevo-mcp==<version>, and v<version> in the address of the constraints.txt file. Then, quit Claude Desktop, and open it again.

After you open Claude Desktop again, the hevo_whoami tool reports the new version.


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