Adding the Hevo MCP Server to Claude Desktop
On This Page
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
-
An active Hevo account. You can start with a 14-day full-feature, free trial account.
-
You are assigned the required role for the actions that you want the agent to perform.
-
You have generated your API credentials, and downloaded or copied them. Read Generating your API Credentials for the steps.
-
uv is installed on your machine. The uv tool runs the server, and downloads the version of Python that the server needs.
-
Claude Desktop is installed on your machine.
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:
-
Run the following commands in a terminal to create the
.hevofolder and move the downloaded file into it ashevo-key.json:mkdir -p ~/.hevo mv "<path to the downloaded file>" ~/.hevo/hevo-key.jsonOn 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
.hevofolder. Then, create thehevo-key.jsonfile in the folder in a text editor, with the following content, and save it as plain text, without a.txtextension:{ "access_key": "<your Access Key>", "secret_key": "<your Secret Key>" } -
Run the following command to allow only you to read the file:
chmod 600 ~/.hevo/hevo-key.jsonOn Windows, run the following commands in PowerShell instead. They allow only you to access the
.hevofolder 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:
-
Run the following command to find the full path of the
uvxcommand:which uvxOn Windows, run the
where.exe uvxcommand in PowerShell instead. -
Add the following entry to the
claude_desktop_config.jsonfile, which is~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS or%APPDATA%\Claude\claude_desktop_config.jsonon 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 asC:\\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
mcpServerskey 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 anmcpServersobject, add only thehevoentry to it. -
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
eu2andus-gcpregions, 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.jsonand is in the.hevofolder 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 600command 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
.hevofolder, 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. |