mcp-hfspace

You can customize the behavior of mcp-hfspace using command-line arguments or environment variables.

Working Directory

By default, the server uses the current working directory for file uploads/downloads, which can be problematic on Windows or macOS. It is highly recommended to set a specific directory using --work-dir or the MCP_HF_WORK_DIR environment variable.

Hugging Face Token

To access private spaces, provide your Hugging Face token using the --hf-token argument or the HF_TOKEN environment variable.

Claude Desktop Mode

In the default Claude Desktop Mode, images are returned in tool responses and other files are saved to the working directory with their paths returned. To disable this and return content as embedded Base64 encoded resources, use --desktop-mode=false or set CLAUDE_DESKTOP_MODE=false.

Specifying API Endpoints

If you need a specific endpoint within a space, append it to the space name (e.g., space/name/endpoint).

{
  "mcpServers": {
    "mcp-hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=/Users/evalstate/mcp-store",
        "--hf-token=hf_...",
        "shuttleai/shuttle-jaguar",
        "styletts2/styletts2",
        "Qwen/QVQ-72B-preview"
      ]
    }
  }
}

Common Issues

• ZeroGPU Quotas: If you encounter errors or long waits, you may have exhausted your Hugging Face ZeroGPU quota. Try again later or duplicate the space to your own account.
• Timeouts: Claude Desktop has a hard timeout of approximately 60 seconds. Large or heavy jobs (especially on ZeroGPU) might timeout. Even if a timeout occurs, check your WORK_DIR; the server may have successfully saved the result.
• Unsupported Endpoints: Endpoints that use unnamed parameters are currently unsupported.
• Claude Desktop Errors: Claude Desktop 0.75 and earlier may not respond well to MCP errors. Use the @modelcontextprotocol/inspector for better diagnostics.

Tips for Success

• Private Spaces: Using an HF_TOKEN allows you to access private spaces and dedicated hardware, which avoids ZeroGPU quotas.
• Working Directory: Always set a dedicated --work-dir to avoid permission issues on macOS or unexpected paths on Windows.

The convertParameter function transforms a Gradio ApiParameter into an MCP-compatible ParameterSchema.

Key Conversion Behaviors:

• File Inputs: If isFileParameter is true, the type is set to "string" and the description is specialized based on the component (e.g., "Accepts: Image file URL, file path, file name, or resource identifier" for Image components).
• Chat History: If the parameter name is "history" and the component is "Chatbot", the type is forced to "array" with a specific description explaining the [user_message, assistant_message] structure.
• Number Constraints: For number types, it parses the description for constraints like "between X and Y" or "min: X"/"max: Y" to populate minimum and maximum fields.
• Literal Types (Enums): If the python_type.type starts with "Literal[", it extracts the comma-separated values to populate the enum field in the schema.
• Defaults and Examples: If parameter_has_default is true, the default key is added. If example_input is present, it is added to an examples array.

Return Shape

Returns an object compatible with Tool["inputSchema"]["properties"] containing type, description, and optional enum, default, examples, minimum, or maximum keys.

The mcp-hfspace server can be configured using command-line arguments or environment variables. If arguments are provided, they take precedence over environment variables.

Configuration Options

Usage Example

To run the server with a specific work directory, a Hugging Face token, and a specific Space path:

node dist/index.js --work-dir ./my-files --hf-token hf_abc123 user/my-space

# Example command line invocation
node dist/index.js --work-dir ./my-files --hf-token hf_abc123 user/my-space

The Gradio API is structured around endpoints that define how to interact with a hosted Gradio space. An ApiStructure contains two types of endpoints: named_endpoints (accessible by a specific name) and unnamed_endpoints (accessed by index).

Each ApiEndpoint defines the input parameters required and the returns object describing the output. Parameters include metadata such as label, type, component (the Gradio UI component type), and python_type which specifies the underlying Python data type and description.

export interface ApiStructure {
  named_endpoints: Record<string, ApiEndpoint>;
  unnamed_endpoints: Record<string, ApiEndpoint>;
}

export interface ApiEndpoint {
  parameters: ApiParameter[];
  returns: ApiReturn[];
  type: {
    generator: boolean;
    cancel: boolean;
  };
}

export interface ApiParameter {
  label: string;
  parameter_name?: string;
  parameter_has_default?: boolean;
  parameter_default?: unknown;
  type: string;
  python_type: {
    type: string;
    description?: string;
  };
  component: string;
  example_input?: string;
  description?: string;
}

export interface ApiReturn {
  label: string;
  type: string;
  python_type: {
    type: string;
    description: string;
  };
  component: string;
}

The mcp-hfspace server provides several built-in tools to interact with Hugging Face Spaces and local files. In addition to tools dynamically generated from configured Hugging Face Spaces (via EndpointWrapper), the following tools are always available:

available-files

Returns a markdown table of available files and resources. Use this tool when the user refers to ambiguous resources like "the most recent image" or "the audio". The table includes resource uri, name, size, last modified, and mime type.

search-spaces

Performs a semantic search to find specific endpoints on the Hugging Face Spaces service.

• Arguments:
  • query (string): The semantic search term (e.g., a 3-7 word description of a task).
• Returns: A markdown table of search results.

### Tool Definitions

| Name | Description | Arguments |
| :--- | :--- | :--- |
| `available-files` | A list of available file and resources... returns 'resource uri', 'name', 'size', 'last modified' and 'mime type' in a markdown table | `{}` |
| `search-spaces` | Use semantic search to find an endpoint on the `Hugging Face Spaces` service... | `{ "query": "string" }` |