LabscoMCP early access ↗
will-shMCP SERVER

HDFS MCP Server

Browse, read and move files on an HDFS cluster through your local Hadoop client.

by will-sh ↗Data Platform: Pipelines, Warehousing, BI & GovernanceCommunity

LABSCO SUMMARY

It borrows your Hadoop client, which is both the setup cost and the payoff.

Nothing here reimplements HDFS access — if hdfs dfs -ls works in your shell, this works too, Kerberos included; if it doesn't, this won't, and the fix is in your Hadoop configuration rather than in the server. That makes it a thin, predictable layer rather than a second thing to authenticate.

What it is

A Python server that fronts an HDFS cluster. It shells out to your configured Hadoop client rather than talking to the NameNode itself, so it inherits whatever authentication and cluster configuration is already working on that machine — including a Kerberos ticket.

What you get

  • Browsing and reading: list directory contents, read file contents, get file or directory information
  • Writing: create directories, upload files to HDFS, download files from HDFS, delete files and directories
  • Moving: copy and move files within HDFS
  • Cluster view: disk usage and cluster status, plus connection testing and error handling meant to be readable

Requirements

Python 3.11 or higher, the uv package manager, and a Hadoop client already installed and configured — HADOOP_HOME set and the hdfs command on your PATH. Clone the repository, run uv venv and uv pip sync, then configure your client to run uv --directory <YOUR_PATH_TO_HDFS_MCP> run hdfs.py with HDFS_NAMENODE and NAMENODE_PORT in the environment; the NameNode port defaults to 8020 if you leave it out. You also need cluster permissions for whatever you intend to do, and a valid Kerberos ticket if the cluster expects one.

Setup effort

Build from source — git clone https://github.com/will-sh/hdfs-mcp.git

See installation options