Enables searching for Gradio spaces for various AI applications like image generation, as part of the Hugging Face Spaces integration.
Provides comprehensive access to the Hugging Face ecosystem, enabling repository management (creating, deleting, and managing models, datasets, and spaces), file operations (reading, writing, editing, and deleting files), search and discovery capabilities, and collections management.
Allows searching for models tagged with PyTorch on Hugging Face as part of the search and discovery capabilities.
HuggingMCP - Advanced Hugging Face MCP Server
A comprehensive and powerful Model Context Protocol (MCP) server for Hugging Face Hub operations, featuring 18+ specialized tools, AI workflow automation, and extensive ML capabilities.
🚀 Features
Core Capabilities
- Optimized Command Structure: 18+ specialized commands covering all aspects of ML workflows
- Enhanced Debugging: Comprehensive stderr output and logging for troubleshooting
- Robust Error Handling: Safe execution wrappers with detailed error reporting and helpful guidance
- Backward Compatibility: All existing commands maintained with enhanced functionality
New Advanced Features
- 🔬 Model Evaluation & Testing: Comprehensive model analysis, validation, and comparison tools
- 🗃️ Dataset Processing: Advanced dataset analysis, validation, and management
- 📝 License Management: Automated license checking, compliance validation, and suggestions
- 🤝 Community Features: Repository likes, discussions, commit history, and social interactions
- 🚀 Space Management: Complete Hugging Face Spaces control and monitoring
- 🧠 AI Inference Tools: Model testing and inference capabilities with multiple strategies
- ⚙️ Workflow Automation: Automated model card generation, README creation, and bulk operations
- 📊 Advanced Analytics: Trending analysis, recommendation engine, and ecosystem insights
- 🛠️ Repository Utilities: Health checks, backup tools, and comprehensive repository management
Enhanced File Operations
- Batch Processing: Edit multiple files with pattern matching
- File Validation: Format-specific validation for JSON, Markdown, Python, etc.
- Backup System: Automatic backup creation before destructive operations
- Advanced Reading: Chunked reading, encoding detection, and size management
📋 Prerequisites
- Python 3.8+
- Required packages:
- Hugging Face token (set as
HF_TOKEN
environment variable)
⚙️ Configuration
Add to your Claude Desktop configuration file at:
/Users/[username]/Library/Application Support/Claude/claude_desktop_config.json
Environment Variables
HF_TOKEN
: Your Hugging Face API token (required for write operations)HF_ADMIN_MODE
: Enable admin operations like repository deletion (default: false)HF_READ_ONLY
: Restrict to read-only operations (default: false)HF_MAX_FILE_SIZE
: Maximum file size for operations in bytes (default: 104857600 = 100MB)HF_ENABLE_INFERENCE
: Enable inference API features (default: true)HF_INFERENCE_TIMEOUT
: Timeout for inference operations in seconds (default: 30)HF_CACHE_ENABLED
: Enable caching for better performance (default: true)
🛠️ Available Commands
Core Commands (Enhanced)
1. hf_system_info()
Get comprehensive system information, configuration, and test connectivity.
2. hf_repository_manager(action, repo_id, repo_type="model", **kwargs)
Comprehensive repository management.
Actions:
create
: Create new repositoryprivate
: Make repository private (default: False)description
: Repository descriptionspace_sdk
: For Spaces - "gradio", "streamlit", "docker", "static"creator
: Repository creator (defaults to authenticated user)
delete
: Delete repository (requires admin mode)info
: Get repository informationlist_files
: List all files in repository
Examples:
3. hf_file_operations(action, repo_id, filename, repo_type="model", **kwargs)
Enhanced file operations with advanced capabilities.
Actions:
read
: Read file content with encoding detectionmax_size
: Maximum characters to read (default: 500,000)chunk_size
: Enable chunked readingchunk_number
: Chunk number to read (for chunked reading)
write
: Write/upload file content with validationcontent
: File content to writecommit_message
: Commit message
edit
: Edit file by replacing text with backupold_text
: Text to replacenew_text
: Replacement textcommit_message
: Commit message
delete
: Delete file from repositoryvalidate
: Validate file format and contentbackup
: Create backup of file before operationsbatch_edit
: Edit multiple files with pattern matchingpattern
: Text pattern to replacereplacement
: Replacement textfile_patterns
: File patterns to match (e.g., [".md", ".txt"])
Examples:
4. hf_search_hub(content_type, query=None, author=None, filter_tag=None, limit=20)
Search Hugging Face Hub for models, datasets, or spaces.
Examples:
5. hf_collections(action, **kwargs)
Manage Hugging Face Collections.
Actions:
create
: Create new collectiontitle
: Collection title (required)namespace
: Collection namespace (defaults to user)description
: Collection descriptionprivate
: Make collection private
add_item
: Add item to collectioncollection_slug
: Collection identifieritem_id
: Item to add (repo ID)item_type
: Type of item ("model", "dataset", "space")note
: Optional note about the item
info
: Get collection informationcollection_slug
: Collection identifier
Examples:
6. hf_pull_requests(action, repo_id, repo_type="model", **kwargs)
Manage Pull Requests.
Actions:
create
: Create empty PRtitle
: PR title (required, min 3 characters)description
: PR description
list
: List PRsstatus
: Filter by status ("open", "closed", "all")author
: Filter by author
details
: Get PR detailspr_number
: PR number to get details for
create_with_files
: Create PR with file changesfiles
: List of {path, content} dictionariescommit_message
: Commit messagepr_title
: PR titlepr_description
: PR description
Examples:
7. hf_upload_manager(action, repo_id, repo_type="model", **kwargs)
Upload management with various options.
Actions:
single_file
: Upload one filefile_path
: Path in repositorycontent
: File contentcommit_message
: Commit message
multiple_files
: Upload multiple filesfiles
: List of {path, content} dictionariescommit_message
: Commit message
with_pr
: Upload file(s) and create PRfile_path
: Path in repositorycontent
: File contentcommit_message
: Commit messagepr_title
: PR titlepr_description
: PR description
8. hf_batch_operations(operation_type, operations)
Execute multiple operations in batch.
Operation Types:
search
: Batch search operationsinfo
: Batch repository info retrievalfiles
: Batch file listing
Example:
9. hf_advanced_search(query, search_types=["models", "datasets", "spaces"], filters=None, limit_per_type=10)
Advanced search across multiple content types with filtering and popularity scoring.
Example:
10. hf_debug_diagnostics()
Comprehensive debugging and diagnostic information.
11. hf_repo_file_manager(action, repo_id, repo_type="model", filename=None, **kwargs)
Unified repository and file management with rename support.
Actions:
repo_create
,repo_delete
,repo_info
,list_files
file_read
,file_write
,file_edit
,file_delete
,file_rename
Example:
New Advanced Commands
12. hf_model_evaluation(action, repo_id, **kwargs)
Advanced model evaluation and testing capabilities.
Actions:
analyze
: Comprehensive model analysis including architecture, frameworks, and compatibilitycompare
: Compare multiple models side by sidetest_inference
: Test model inference capabilities (if supported)validate_model
: Validate model integrity and completeness
Examples:
13. hf_space_management(action, space_id, **kwargs)
Advanced Hugging Face Spaces management.
Actions:
runtime_info
: Get space runtime information and statusrestart
: Restart a spacepause
: Pause a spaceset_sleep_time
: Set sleep time for a spaceduplicate
: Duplicate a space to a new location
Examples:
14. hf_community_features(action, repo_id, repo_type="model", **kwargs)
Community features and social interactions.
Actions:
like
: Like a repositoryunlike
: Unlike a repositoryget_likes
: Get user's liked repositoriescreate_discussion
: Create a discussion (non-PR)get_commits
: Get repository commit historyget_refs
: Get repository branches and tags
Examples:
15. hf_dataset_processing(action, dataset_id, **kwargs)
Advanced dataset processing and analysis tools.
Actions:
analyze
: Analyze dataset structure, size, and metadatacompare
: Compare multiple datasetsvalidate
: Validate dataset format and completeness
Examples:
16. hf_license_management(action, repo_id, repo_type="model", **kwargs)
License management and compliance tools.
Actions:
check_license
: Check repository license informationvalidate_compliance
: Validate license compliance with scoringsuggest_license
: Suggest appropriate license based on content type and preferences
Examples:
17. hf_inference_tools(action, repo_id, **kwargs)
Advanced inference and model testing tools.
Actions:
test_inference
: Test model inference with custom inputscheck_endpoints
: Check available inference endpoints
Examples:
18. hf_ai_workflow_tools(action, **kwargs)
Specialized AI workflow and automation tools.
Actions:
create_model_card
: Generate comprehensive model cardsbulk_operations
: Perform bulk operations across repositoriesgenerate_readme
: Generate README files for repositoriesvalidate_pipeline
: Validate complete ML pipelines
Examples:
19. hf_advanced_analytics(action, **kwargs)
Advanced analytics and insights for HuggingFace repositories.
Actions:
trending_analysis
: Analyze trending models/datasets with metricsrecommendation_engine
: Recommend repositories based on preferences
Examples:
20. hf_repository_utilities(action, repo_id, repo_type="model", **kwargs)
Advanced repository utilities and management tools.
Actions:
repository_health
: Comprehensive repository health check with scoringbackup_info
: Create comprehensive backup information
Examples:
🔧 Debugging
The server includes comprehensive debugging features:
- Stderr Output: Real-time debugging information printed to stderr
- Log Files: Detailed logs written to
/tmp/hugmcp_debug.log
- Diagnostic Tools: Use
hf_debug_diagnostics()
for system health checks - Error Tracking: Comprehensive error handling with stack traces
Debug Log Locations
- MCP Logs:
/Users/[username]/Library/Logs/Claude/mcp-server-huggingmcp.log
- Debug Logs:
/tmp/hugmcp_debug.log
🛡️ Security & Permissions
- Authentication: Requires HF_TOKEN for write operations
- Read-Only Mode: Set
HF_READ_ONLY=true
to prevent modifications - Admin Mode: Set
HF_ADMIN_MODE=true
to enable repository deletion - File Size Limits: Configurable via
HF_MAX_FILE_SIZE
🐛 Troubleshooting
Common Issues
- Server Disconnects Immediately
- Check if the script path in configuration is correct
- Verify Python dependencies are installed
- Check debug logs for detailed error information
- Authentication Errors
- Ensure
HF_TOKEN
is set correctly - Verify token has required permissions
- Check token validity at huggingface.co
- Ensure
- File Path Errors
- Verify the script is at
/Users/sshpro/Documents/hugmcp.py
- Check file permissions (should be readable/executable)
- Verify the script is at
- Import Errors
- Install required packages:
pip install mcp huggingface_hub
- Check Python version compatibility
- Install required packages:
Getting Help
- Use
hf_debug_diagnostics()
for system information - Check stderr output for real-time debugging
- Review log files for detailed error traces
- Verify configuration in Claude Desktop settings
📝 Version History
v3.0.0 (Current) - Major Feature Release
- Massive expansion: Added 9+ new advanced command categories (18+ total tools)
- 🔬 Model Evaluation: Complete model analysis, comparison, and validation system
- 🗃️ Dataset Processing: Advanced dataset analysis and validation tools
- 📝 License Management: Automated license checking and compliance validation
- 🤝 Community Features: Repository likes, discussions, commit history, social interactions
- 🚀 Space Management: Complete Hugging Face Spaces control and monitoring
- 🧠 AI Inference Tools: Model testing and inference capabilities
- ⚙️ Workflow Automation: Model card generation, README creation, bulk operations
- 📊 Advanced Analytics: Trending analysis, recommendation engine, ecosystem insights
- 🛠️ Repository Utilities: Health checks, backup tools, comprehensive management
- Enhanced File Operations: Batch editing, validation, backup system, format detection
- Improved Error Handling: Detailed validation, helpful error messages, guided troubleshooting
- Graceful Degradation: Feature detection for different huggingface_hub versions
- Backward Compatibility: All existing v2.x commands maintained and enhanced
v2.1.0
- Consolidated 23+ commands into 11 optimized commands
- Added unified repo/file manager with rename support
- Enhanced debugging and error handling
- Added batch operations and advanced search
- Improved file operations with chunked reading
- Added comprehensive diagnostics
- Fixed metadata and connection stability issues
📄 License
This project is licensed under the MIT License.
🤝 Contributing
Contributions are welcome! Please ensure all changes maintain the current command structure and include appropriate error handling and debugging output.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server that allows Claude and other MCP-compatible AI assistants to interact with the Hugging Face ecosystem, enabling repository management, file operations, search, and collections management through natural language.
- 🚀 Features
- 📋 Prerequisites
- ⚙️ Configuration
- 🛠️ Available Commands
- Core Commands (Enhanced)
- hf_system_info()
- hf_repository_manager(action, repo_id, repo_type="model", **kwargs)
- hf_file_operations(action, repo_id, filename, repo_type="model", **kwargs)
- hf_search_hub(content_type, query=None, author=None, filter_tag=None, limit=20)
- hf_collections(action, **kwargs)
- hf_pull_requests(action, repo_id, repo_type="model", **kwargs)
- hf_upload_manager(action, repo_id, repo_type="model", **kwargs)
- hf_batch_operations(operation_type, operations)
- hf_advanced_search(query, search_types=["models", "datasets", "spaces"], filters=None, limit_per_type=10)
- hf_debug_diagnostics()
- hf_repo_file_manager(action, repo_id, repo_type="model", filename=None, **kwargs)
- New Advanced Commands
- hf_model_evaluation(action, repo_id, **kwargs)
- hf_space_management(action, space_id, **kwargs)
- hf_community_features(action, repo_id, repo_type="model", **kwargs)
- hf_dataset_processing(action, dataset_id, **kwargs)
- hf_license_management(action, repo_id, repo_type="model", **kwargs)
- hf_inference_tools(action, repo_id, **kwargs)
- hf_ai_workflow_tools(action, **kwargs)
- hf_advanced_analytics(action, **kwargs)
- hf_repository_utilities(action, repo_id, repo_type="model", **kwargs)
- 🔧 Debugging
- 🛡️ Security & Permissions
- 🐛 Troubleshooting
- 📝 Version History
- 📄 License
- 🤝 Contributing
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that connects Claude and other MCP clients to Aider, enabling AI assistants to efficiently edit files, create new files, and interact with git repositories through natural language.Last updated -9PythonThe Unlicense
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.Last updated -104PythonMIT License
- -securityAlicense-qualityA Model Context Protocol server that provides Claude and other LLMs with read-only access to Hugging Face Hub APIs, enabling interaction with models, datasets, spaces, papers, and collections through natural language.Last updated -4PythonMIT License
- AsecurityFlicenseAqualityA Model Context Protocol (MCP) server that allows Claude AI to interact with custom tools, enabling extension of Claude's capabilities through the MCP framework.Last updated -TypeScript