How to connect Hugging Face Hub MCP with Python

Inspect the current Hugging Face authentication context, including the account, visible organization memberships, and credential access details. Read-only and never returns credential values.

Search Hugging Face repositories with a shared query interface. You can target models, datasets, spaces, or aggregate across multiple repo types in one call. Include links to repositories in your response.

Create a Hugging Face model, dataset, Space, or bucket repository using an hf:// destination URI. Set source_uri to duplicate an existing model, dataset, or Space server-side.

Get details for one or more Hugging Face repos (model, dataset, or space). Auto-detects type unless specified. For datasets, use operations: overview, dataset_structure, dataset_preview. Use dataset_structure first to discover configs, splits, sizes, and schema. Use dataset_preview only when config and split are known, unless the dataset has a single config/split.

When to use: Hugging Face Hub models, datasets, Spaces, collections, papers, daily papers, today's trending models, current paper leaderboard, docs, and repository files. Examples: {"operations":[{"cmd":"ls","args":["hf://models/trending","--limit","10"]}]} {"operations":[{"cmd":"ls","args":["hf://papers/trending"]}]} {"operations":[{"cmd":"ls","args":["hf://papers/daily/latest"]}]} {"operations":[{"cmd":"cat","args":["hf://papers/2501.00001/paper.md"]}]} Use hf_fs for Hugging Face Hub filesystem operations. Call it with operations, an array of {cmd, args} items; multiple operations may be submitted together. Usage: {"operations":[{"cmd":"ls","args":["hf://models/org/repo"]}]} Grammar; each string below is one args array item: ls URI [--recursive] [--glob GLOB] [--type TYPE] [--sort SORT] [--limit N] cat URI [--offset N] [--max-bytes N] attach URI [--max-bytes N] stat URI find URI [--name GLOB] [--path GLOB] [--type TYPE] [--limit N] search URI [QUERY] [--type TYPE] [--sort SORT] [--tag TAG] [--kind mcp] [--limit N] COMMAND = ls|cat|attach|stat|find|search. TYPE = file|dir|repo|bucket|collection|paper|link. SORT = createdAt|downloads|likes|lastModified|likes30d|trendingScore|mainSize|id|trending|upvotes. URI is a canonical hf:// URI. QUERY and GLOB are each one string. Use search for resource discovery, not repository-content search; ls for a known directory, find for recursive file discovery by name/path (not file contents), stat for filesystem metadata or an uncertain target type, cat for text contents, and attach for a complete JPEG, PNG, or WebP image. When the request gives an exact text-file URI, use cat directly; do not add ls or stat first. stat does not read the contents of JSON, Markdown, or other text files. Search scopes: hf://models[/OWNER], hf://datasets[/OWNER], hf://spaces[/OWNER], hf://collections[/OWNER], hf://papers, and hf://docs[/...]. Repository and repository-file scopes are not supported: search a resource root or owner scope to discover resources; use find for file discovery within a repository or cat for a known text file. Paper and documentation search require QUERY. --tag (repeatable) and --kind are supported only on exactly hf://spaces, not owner scopes or other roots. The only valid --kind value is mcp, which selects MCP Spaces. Use ls hf://models/trending, hf://datasets/trending, hf://spaces/trending, or hf://papers/trending for trending listings. hf://papers/ID is a paper directory, not paper text. Use cat hf://papers/ID/paper.md for paper text and cat hf://papers/ID/metadata.json for metadata. No preliminary listing is needed for these known paths. Use ls hf://papers/ID to discover other resources. Omit --limit, --sort, and --type unless the request requires them. Limits and path-specific behavior are documented at hf://README.md. Issue one hf_fs call.

Write or remove files in Hugging Face repositories and buckets. Grammar; each token below is one args array element: put URI [--base64] [(-m|--message) MESSAGE] [--description DESCRIPTION] [--branch BRANCH] [--create-pr] [--parent-commit SHA] rm URI [(-m|--message) MESSAGE] [--description DESCRIPTION] [--branch BRANCH] [--create-pr] [--parent-commit SHA] URI must be an hf://models|datasets|spaces|buckets/OWNER/NAME/PATH file URI. For put, provide file data in the separate content field. Content is UTF-8 text unless --base64 is present. Use --create-pr to propose a change when direct repository writes are unavailable or undesirable. Branches, pull requests, descriptions, and parent commits are not supported for buckets. A URI '@revision' and --branch are equivalent; do not specify conflicting values. --parent-commit must be a 40-character Git commit SHA and prevents overwriting concurrent changes. No pipes, redirects, shell expansion, or multiple commands.

Remote compute for Hugging Face workflows. Run Python/UV or Docker jobs to deeply analyze Hub datasets, repos, traces, models, and large files; compute trends/statistics; run batch inference/evaluation; or perform long-running work with installed libraries. Use for dataset/repo analysis prompts when local chat inspection is insufficient. Includes submit, logs, inspect, cancel, schedule, and volume mounting. Minimal run: {"operation":"run","args":{"image":"python:3.12","command":["python","-c","print(123)"]}}. Command arrays are literal argv; strings tokenize quotes and escaping, not shell execution. For pipes, chaining, redirections, or variable expansion, explicitly use ["/bin/sh", "-lc", "..."] only if the image provides that shell. Help: {"operation":"run","args":{"help":true}}; full usage: {}. Follow up with logs or inspect using args: {"job_id":"<returned job ID>"}.

Create and manage Hugging Face Sandboxes. Grammar; each token below is one args array element: create [--name NAME] [--image IMAGE] [--flavor FLAVOR] [--timeout DURATION] [--namespace NAMESPACE] [--resource-group-id ID] [--forward-hf-token] [--volume SPEC]... [--bucket OWNER/NAME] [--bucket-mode ro|rw] [--bucket-mount-path PATH] status HANDLE terminate HANDLE ps HANDLE kill HANDLE PROCESS_ID HANDLE is returned by create. Volume SPEC is hf://[models|datasets|spaces|buckets]/OWNER/NAME[/PATH]:/MOUNT_PATH[:ro|:rw]. No pipes, redirects, shell expansion, or multiple commands.

Run a shell command inside a Hugging Face Sandbox. Grammar; each token below is one args array element: exec HANDLE SHELL_COMMAND [--workdir PATH] [--stdin TEXT] [--timeout SECONDS] [--env NAME=VALUE]... [--detach] [--tag TAG] SHELL_COMMAND is one string token and runs via /bin/sh -lc. Foreground timeout defaults to 30 seconds and may not exceed 55. Detached commands have no timeout unless set. Redirect detached output to a file.

Read, write and manage files inside a Hugging Face Sandbox. Grammar; each token below is one args array element: ls HANDLE PATH cat HANDLE PATH [--offset N] [--max-bytes N] stat HANDLE PATH write HANDLE PATH (--text TEXT|--base64 BASE64) rm HANDLE PATH [(-r|-R|--recursive)] mkdir HANDLE PATH PATH is an absolute path inside the sandbox. cat defaults to 20000 bytes and allows at most 100000.

Perform Tasks with Hugging Face Spaces. Use "discover" to view available Tasks. Examples are Image Generation/Editing, Background Removal, Text to Speech, OCR and many more. Call with no arguments for full usage instructions.

Generate an image using the Z-Image model based on the provided prompt and settings. This function is triggered when the user clicks the "Generate" button. It processes the input prompt (optionally enhancing it), configures generation parameters, and produces an image using the Z-Image diffusion transformer pipeline. Returns: tuple: (gallery_images, seed_str, seed_int), - seed_str: String representation of the seed used for generation, - seed_int: Integer representation of the seed used for generation (from mcp-tools/Z-Image-Turbo)