Setting up the Hevo MCP Server in Claude

Last updated on Nov 18, 2026

You can use the Hevo MCP server in Claude Code and in Claude Desktop. In Claude Code, the Hevo plugin installs the server and the hevo-pipelines skill in one step. In Claude Desktop, you add the hevo-mcp package from PyPI to the settings of Claude Desktop. In both, the server runs on your machine, and your requests go from your machine directly to Hevo.


Requirements

You need the following to set up the server in Claude Code or Claude Desktop:

  • API credentials: Your Access Key and Secret Key, saved in the ~/.hevo/hevo-key.json key file. The server reads your API credentials only from this file, and never shows them to the agent.

  • uv: The uv tool, which runs the server and downloads the version of Python that the server needs.

  • Python 3.12: For Claude Code, Python 3.12 installed on your machine.

  • Claude Code or Claude Desktop: The agent in which you want to use the server, installed on your machine.


Differences between Claude Code and Claude Desktop

The following table lists how you work with the server in Claude Code and in Claude Desktop:

Task Claude Code Claude Desktop
Set up the server Install the Hevo plugin, which adds the server and the hevo-pipelines skill. Add the hevo-mcp package from PyPI to the claude_desktop_config.json file.
Start using the server after you set it up or update it Exit Claude Code, and start a new Claude Code session. Quit Claude Desktop, and open it again.
Allow the agent to make changes Add export HEVO_MCP_DEFAULT_SCOPE=write (or delete) to your shell profile file, such as ~/.zshrc, or on Windows, run setx HEVO_MCP_DEFAULT_SCOPE write in PowerShell. Then, start a new Claude Code session from a new terminal. Add "HEVO_MCP_DEFAULT_SCOPE": "write" (or "delete") to the env settings of the server in the claude_desktop_config.json file. Then, quit Claude Desktop, and open it again.
Use the hevo-pipelines skill Claude Code uses the skill when you ask about Hevo. To run it yourself, use the /hevo-data:hevo-pipelines command. The server sends the key rules of the skill when it connects, and provides the full skill as a resource.
Approve a change Answer the approval prompt that the server shows. Approval prompts work in a terminal, but not in print mode or in the Visual Studio Code extension. Not supported. Claude Desktop cannot show approval prompts, so the agent cannot make the changes that need your approval.

Read Allowing and Approving Changes by your Agent for more information about scopes and approval prompts.


Setup Steps

Refer to the following pages for the steps to set up the server in Claude Code or Claude Desktop:


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