Hue

You can connect an AI assistant to Hadoop Hue through this MCP server to run SQL queries, manage HDFS files, and export results as CSV. It exposes HueClientRest capabilities in a standardized way so your Copilot or Claude Desktop workflows can interact with Hue securely and reliably.

How to use

You interact with the Hue MCP Server through your MCP client (for example, VS Code Copilot or Claude Desktop). Start by ensuring the MCP server is running in the background and that your Hue credentials are available as environment variables. You can then ask your assistant to: execute Hive/SparkSQL/Impala queries, list or transfer files in HDFS, export query results to CSV, or browse directory structures. Tools are exposed as natural-language actions such as executing a query, exporting to CSV, listing directories, downloading files, and uploading files.

How to install

Follow these steps to set up the Hue MCP Server from scratch. They assume you want to run the MCP server locally using the standard uv workflow and also provide a Python-based alternative for execution.

# Prerequisites
- Python 3.10 or higher
- Astral uv
- Visual Studio Code (for MCP integration)
- GitHub Copilot subscription (for Copilot integration)
- Access to a Hadoop Hue server (host, username, password)

# Step 1: Install Astral uv
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

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

uv --version

# Step 2: Install the project (via uv) - clone and install dependencies

# Replace <your-repo-url> with the actual repository URL you cloned
git clone <your-repo-url>
cd hueclientrest-mpc
uv sync

# Optional: use pip instead of uv
# pip install -e .

# Step 3: Set up environment variables for Hue access (see the environment variable guide below)

# Optional alternative: prepare a development environment using Python directly
# Create and activate a virtual environment, then install dependencies
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate  # Windows
pip install -e .

Environment variables you need for Hue access

You must provide Hue connection details so the MCP server can authenticate and communicate with Hue REST APIs.

# Create a .env file in the project root for local development
HUE_HOST=https://your-hue-server.com
HUE_USERNAME=your_username
HUE_PASSWORD=your_password
HUE_VERIFY_SSL=true
HUE_SSL_WARNINGS=false

You can also set these variables in your system environment if you prefer not to use a local .env file.

Starting the MCP server from VS Code or the command line

Two common ways to start the Hue MCP Server are shown here. Choose the method you prefer and ensure the environment variables above are accessible to the process.

# Option 1: Start via UV with a local project directory (Windows example shown)
uv run --directory C:\Projects\hueclientrest-mpc hue-mcp-server

# Option 2: Start via Python module directly (Windows)
C:\Projects\hueclientrest-mpc\.venv\Scripts\python.exe -m hue_mcp_server.server

# macOS/Linux equivalent
uv run --directory /path/to/hueclientrest-mpc hue-mcp-server
uv run python -m hue_mcp_server.server

Notes on integration with editors and Copilot

For an integrated workflow with editors that support MCP, add the Hue MCP server configuration to your editor or Copilot setup so it can discover and expose the Hue tools to your AI assistant.

If you prefer a direct JSON configuration for your editor, use the provided example configurations in the configuration section.

Configuration and security considerations

Keep credentials secure by using environment variables or secret stores. Do not commit credentials to version control. Use SSL verification in production and consider rotating Hue passwords periodically.

SSL verification may be disabled only for testing with self-signed certificates. In production, set HUE_VERIFY_SSL=true and HUE_SSL_WARNINGS=false.

Development and testing

You can test your MCP server interactively with the MCP inspector. Run the server in development mode and verify that each Hue tool is exposed and returns the expected results.

uv run mcp dev src/hue_mcp_server/server.py

Troubleshooting quick-start

If the Hue MCP Server does not appear in your editor’s Copilot tools yet, validate that uv is installed, the project dependencies are installed, and the mcp configuration path is correct for your OS. Restart your editor after changes.

Project structure overview

The project is organized to separate the MCP server logic, Hue client interactions, and development tooling. This structure helps you extend tools or adjust integrations as your Hue setup evolves.

Available tools

hue_execute_query

Execute a SQL query against Hue using Hive, SparkSQL, or Impala dialects and return results directly.

hue_run_query_to_csv

Run a Hue SQL query and save the results to a CSV file, returning the filename or path.

hue_export_and_download

Execute a query that writes to an HDFS directory and download the resulting files locally.

hue_list_directory

List contents of an HDFS directory including files and subdirectories.

hue_check_directory_exists

Check whether a given HDFS directory exists.

hue_download_file

Download a single file from HDFS to a local path.

hue_download_directory

Download all files from an HDFS directory to a local directory, with optional filtering.

hue_upload_file

Upload a local file to a specified HDFS destination directory.