Hugging Face MCP Server

Instructions

Implementation Reference

• src/huggingface/server.py:246-283 (handler)

  Handler logic for executing the 'search-models' tool: parses arguments, queries the Hugging Face 'models' API endpoint, handles errors, formats model information (id, name, author, tags, downloads, likes, lastModified), and returns JSON as TextContent.

  if name == "search-models":
      query = arguments.get("query")
      author = arguments.get("author")
      tags = arguments.get("tags")
      limit = arguments.get("limit", 10)
  
      params = {"limit": limit}
      if query:
          params["search"] = query
      if author:
          params["author"] = author
      if tags:
          params["filter"] = tags
  
      data = await make_hf_request("models", params)
  
      if "error" in data:
          return [
              types.TextContent(
                  type="text", text=f"Error searching models: {data['error']}"
              )
          ]
  
      # Format the results
      results = []
      for model in data:
          model_info = {
              "id": model.get("id", ""),
              "name": model.get("modelId", ""),
              "author": model.get("author", ""),
              "tags": model.get("tags", []),
              "downloads": model.get("downloads", 0),
              "likes": model.get("likes", 0),
              "lastModified": model.get("lastModified", ""),
          }
          results.append(model_info)
  
      return [types.TextContent(type="text", text=json.dumps(results, indent=2))]

• src/huggingface/server.py:58-82 (registration)

  Registration of the 'search-models' tool in list_tools(), including name, description, and inputSchema defining properties for query, author, tags, and limit.

  types.Tool(
      name="search-models",
      description="Search for models on Hugging Face Hub",
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Search term (e.g., 'bert', 'gpt')",
              },
              "author": {
                  "type": "string",
                  "description": "Filter by author/organization (e.g., 'huggingface', 'google')",
              },
              "tags": {
                  "type": "string",
                  "description": "Filter by tags (e.g., 'text-classification', 'translation')",
              },
              "limit": {
                  "type": "integer",
                  "description": "Maximum number of results to return",
              },
          },
      },
  ),

• src/huggingface/server.py:62-81 (schema)

  JSON Schema for 'search-models' tool input, defining optional properties: query (string), author (string), tags (string), limit (integer).

      "type": "object",
      "properties": {
          "query": {
              "type": "string",
              "description": "Search term (e.g., 'bert', 'gpt')",
          },
          "author": {
              "type": "string",
              "description": "Filter by author/organization (e.g., 'huggingface', 'google')",
          },
          "tags": {
              "type": "string",
              "description": "Filter by tags (e.g., 'text-classification', 'translation')",
          },
          "limit": {
              "type": "integer",
              "description": "Maximum number of results to return",
          },
      },
  },

• src/huggingface/server.py:36-47 (helper)

  Helper function make_hf_request used by the search-models handler to query the HF API endpoints with error handling.

  async def make_hf_request(
      endpoint: str, params: Optional[Dict[str, Any]] = None
  ) -> Dict:
      """Make a request to the Hugging Face API with proper error handling."""
      url = f"{HF_API_BASE}/{endpoint}"
      try:
          response = await http_client.get(url, params=params)
          response.raise_for_status()
          return response.json()
      except Exception as e:
          return {"error": str(e)}