README.md

---
title: A1d Mcp Server
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
license: mit
tags:
  - mcp-server-track
---

# A1D MCP Server - Universal AI Tools

A powerful MCP (Model Context Protocol) server built with Gradio that provides AI image and video processing tools for any MCP-compatible client. This server implements the same tools as the original [A1D MCP Server](https://github.com/AIGC-Hackers/mcp-server) but uses Gradio for easy deployment and hosting.

## 🎥 Demo

**MCP Server in Action**: [View Demo Recording](https://huggingface.co/spaces/aigchacker/a1d-mcp-server)

*The demo shows the A1D MCP Server working with Claude Desktop and other MCP clients, featuring real-time AI image processing, seamless integration, and live preview of results.*

## 🤖 Available AI Tools

| Tool | Description | Use Cases |
|------|-------------|-----------|
| **remove_bg** | AI background removal | Remove backgrounds from photos, product images |
| **image_upscaler** | AI image enhancement | Upscale images 2x, 4x, 8x, 16x resolution |
| **video_upscaler** | AI video enhancement | Improve video quality and resolution |
| **image_vectorization** | Convert to vectors | Turn images into scalable SVG graphics |
| **image_extends** | Smart image extension | Expand image boundaries intelligently |
| **image_generator** | Text-to-image AI | Generate images from text descriptions |

## 🚀 Quick Setup

### 1. Get Your API Key
- Visit [A1D.ai](https://a1d.ai/home/api) to get your free API key
- Optional: [Purchase credits](https://a1d.ai/pricing) for extended usage

### 2. Set Environment Variable
```bash
export A1D_API_KEY=your_api_key_here
```

### 3. Install Dependencies
```bash
pip install -r requirements.txt
```

### 4. Run the Server

**Option 1: Using the startup script (Recommended)**
```bash
python start_server.py
```

**Option 2: Direct execution**
```bash
python app.py
```

**Option 3: Using virtual environment**
```bash
source venv/bin/activate  # On Windows: venv\Scripts\activate
python start_server.py
```

The server will start on `http://localhost:7860` with MCP server enabled.

### 5. Test the Installation
```bash
python test_app.py
```

This will run a comprehensive test suite to verify everything is working correctly.

## 🔧 MCP Server Features

This Gradio app serves as both a **web interface** and a **full MCP server**, providing:

### ✅ **Dual Interface Support**
- **Web UI**: Interactive Gradio interface at `http://localhost:7860`
- **MCP Server**: Protocol-compliant server at `http://localhost:7860/gradio_api/mcp/sse`

### ✅ **Real-time Processing**
- **Async Task Handling**: Uses SSE for real-time status updates
- **Live Preview**: Immediate media preview in both web and MCP clients
- **Progress Tracking**: Detailed logs of API calls and processing status

### ✅ **Production Ready**
- **Error Handling**: Comprehensive error management and user feedback
- **API Integration**: Direct integration with A1D.ai services
- **Scalable**: Can handle multiple concurrent requests

## 🔧 MCP Client Configuration

### ⚠️ API Key Required for Client Usage

When using with your own MCP client (Claude Desktop, Cursor, etc.), you **must** provide your API key:

```json
{
  "mcpServers": {
    "a1d": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "http://localhost:7860/gradio_api/mcp/sse",
        "--header",
        "API_KEY:${MCP_API_KEY}"
      ],
      "env": {
        "MCP_API_KEY": "your_a1d_api_key_here"
      }
    }
  }
}
```

**🔑 API key is mandatory for client usage.** Get your API key at [A1D.ai](https://a1d.ai/home/api).

### For Other MCP Clients
- **Server URL:** `http://localhost:7860/gradio_api/mcp/sse`
- **Transport Type:** SSE (Server-Sent Events)
- **Protocol:** MCP 1.0 compatible
- **Authentication:** API key via `API_KEY` header or environment variable

### Configuration File Locations

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`

## 🌐 Hosted Version

This server is also available as a hosted Hugging Face Space:
- **Space URL:** [https://huggingface.co/spaces/aigchacker/a1d-mcp-server](https://huggingface.co/spaces/aigchacker/a1d-mcp-server)
- **MCP Endpoint:** `https://aigchacker-a1d-mcp-server.hf.space/gradio_api/mcp/sse`

### 🔧 Environment Variables for Hugging Face Space

To deploy this on your own Hugging Face Space:

1. **Fork or duplicate this Space**
2. **Go to Settings → Variables and secrets**
3. **Add the following environment variable:**
   - **Name**: `A1D_API_KEY`
   - **Value**: Your A1D API key from [A1D.ai](https://a1d.ai/home/api)
   - **Type**: Secret (recommended for security)
4. **Save and restart the Space**

### 🔗 MCP Client Configuration for Hosted Version

#### ⚠️ API Key Required for Client Usage

When using with your own MCP client (Claude Desktop, Cursor, etc.), you **must** provide your API key:

```json
{
  "mcpServers": {
    "a1d-hosted": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://aigchacker-a1d-mcp-server.hf.space/gradio_api/mcp/sse",
        "--header",
        "API_KEY:${MCP_API_KEY}"
      ],
      "env": {
        "MCP_API_KEY": "your_a1d_api_key_here"
      }
    }
  }
}
```

**🔑 API key is mandatory for client usage.** Get your API key at [A1D.ai](https://a1d.ai/home/api).

#### 🌐 Using the Hosted Demo on Hugging Face Space

The hosted demo at [https://huggingface.co/spaces/aigchacker/a1d-mcp-server](https://huggingface.co/spaces/aigchacker/a1d-mcp-server) uses our provided API key for demonstration purposes only, with limited usage. For production use, please obtain your own API key.

## 💡 How to Use

Once configured, simply ask your AI assistant to help with image or video tasks:

- *"Remove the background from this image: https://example.com/photo.jpg"*
- *"Upscale this image to 4x resolution: https://example.com/image.png"*
- *"Convert this photo to a vector graphic: https://example.com/logo.jpg"*
- *"Generate an image of a sunset over mountains"*

## 🛠️ Development

### Local Development
```bash
git clone https://github.com/your-repo/a1d-mcp-server-hf.git
cd a1d-mcp-server-hf
pip install -r requirements.txt
export A1D_API_KEY=your_api_key_here
python app.py
```

### Project Structure
```
a1d-mcp-server-hf/
├── app.py              # Main Gradio application
├── config.py           # Configuration settings
├── utils.py            # Utility functions and API client
├── mcp_handler.py      # MCP request handler with header-based API keys
├── start_server.py     # Server startup script
├── test_app.py         # Test suite
├── requirements.txt    # Python dependencies
├── .env.example        # Environment variables example
├── .gitignore          # Git ignore file
├── LICENSE             # MIT license
└── README.md          # This file
```

## 🔐 Security

- **User-provided credentials**: This server supports multiple API key methods:
  - **Header-based**: API keys passed via MCP client headers (recommended)
  - **Environment variables**: Server-side API key configuration
- **No stored secrets**: All API keys are handled per-request, nothing is stored server-side
- **Multi-user support**: Each user can use their own API key via headers
- **HTTPS recommended**: Use HTTPS in production environments

## 🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Follow the existing code style
4. Add tests for new features
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Related Projects

- **Original MCP Server:** [AIGC-Hackers/mcp-server](https://github.com/AIGC-Hackers/mcp-server)
- **A1D API Documentation:** [A1D.ai API Docs](https://a1d.ai/api/quick-start)
- **Gradio MCP Guide:** [Building MCP Server with Gradio](https://www.gradio.app/guides/building-mcp-server-with-gradio)

---

**Built with ❤️ by the A1D Team**
[A1D.ai](https://a1d.ai) • [GitHub](https://github.com/AIGC-Hackers) • [API Docs](https://a1d.ai/api/quick-start)