# AB Download Manager MCP Server (`abdm-mcp`)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP Specification](https://img.shields.io/badge/MCP-2.0+-green.svg)](https://modelcontextprotocol.io/)
[![CI](https://github.com/shivamtawari/ab-download-manager-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/shivamtawari/ab-download-manager-mcp/actions)

MCP server for [AB Download Manager](https://abdownloadmanager.com). Connects AI coding assistants and autonomous agents ([Claude Desktop](https://claude.ai/download), [OpenAI Codex & ChatGPT](https://openai.com), [Google Antigravity](https://github.com/google/antigravity), [Kimi](https://kimi.moonshot.cn/), [Cursor](https://cursor.com), [Windsurf](https://codeium.com/windsurf), [Cline](https://github.com/cline/cline), [Zed](https://zed.dev)) to ABDM so they can offload large downloads—model weights, datasets, and archives—with multi-threaded acceleration (up to 32 connections), pause/resume, and queueing instead of choking on single-threaded agent HTTP calls.

---

## Quick Start

### Run with `uvx` (No installation needed)

```bash
uvx abdm-mcp
```

### Network Transports (SSE & HTTP)

```bash
# Run with Server-Sent Events (SSE) for remote/containerized agents
uvx abdm-mcp --transport sse --port 8000

# Run with Streamable HTTP
uvx abdm-mcp --transport streamable-http --port 8000
```

### Install with `pip`

```bash
pip install abdm-mcp
python -m abdm_mcp
```

---

## Agent Configuration

`abdm-mcp` complies with the Model Context Protocol standard and works across all major AI coding agents, IDEs, and assistant platforms.

### 1. Claude Desktop
Add to your `claude_desktop_config.json`:
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "abdm": {
      "command": "uvx",
      "args": ["abdm-mcp"],
      "env": {
        "ABDM_MCP_DEFAULT_MODE": "interactive",
        "ABDM_API_KEY": "your_api_key_if_configured"
      }
    }
  }
}
```

### 2. OpenAI Codex & ChatGPT Desktop
Add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project-scoped):

```toml
[mcp_servers.abdm]
command = "uvx"
args = ["abdm-mcp"]
env = { "ABDM_MCP_DEFAULT_MODE" = "headless" }
```

Or add via the Codex CLI:
```bash
codex mcp add abdm -- uvx abdm-mcp
```

### 3. Google Antigravity
Add to your workspace or user `mcp.json`:

```json
{
  "mcpServers": {
    "abdm": {
      "command": "uvx",
      "args": ["abdm-mcp"]
    }
  }
}
```

### 4. Kimi (Moonshot AI / Kimi CLI)
Add to your Kimi Agent configuration (`kimi_mcp.json` or agent settings):

```json
{
  "mcpServers": {
    "abdm": {
      "command": "uvx",
      "args": ["abdm-mcp"],
      "env": {
        "ABDM_MCP_DEFAULT_MODE": "headless"
      }
    }
  }
}
```

### 5. Cursor
Add to your project's `.cursor/mcp.json` or Cursor Settings > Features > MCP:

```json
{
  "mcpServers": {
    "abdm": {
      "command": "uvx",
      "args": ["abdm-mcp"]
    }
  }
}
```

### 6. Windsurf (Codeium)
Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "abdm": {
      "command": "uvx",
      "args": ["abdm-mcp"]
    }
  }
}
```

### 7. Cline & Roo Code (VS Code)
Open Settings in Cline / Roo Code and add under MCP Servers:

```json
{
  "mcpServers": {
    "abdm": {
      "command": "uvx",
      "args": ["abdm-mcp"]
    }
  }
}
```

### 8. Zed Editor
Add to `~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "abdm": {
      "command": {
        "env": {},
        "path": "uvx",
        "args": ["abdm-mcp"]
      }
    }
  }
}
```

### 9. Continue.dev
Add to `~/.continue/config.json`:

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["abdm-mcp"]
        }
      }
    ]
  }
}
```

### 10. Goose (Block)
Run the extension add command or add to `~/.config/goose/config.yaml`:

```bash
goose configure add-extension --name abdm --command uvx --args abdm-mcp
```

---

## Tool Surface & Capabilities

All tools return strongly-typed Pydantic schemas and include explicit MCP Tool Annotations:

| Tool Name | Parameters | MCP Annotations | Description |
| :--- | :--- | :--- | :--- |
| `abdm_download` | `url` (str)<br>`mode` ("interactive" \| "headless")<br>`filename` (str, optional)<br>`subdirectory` (str, optional)<br>`queue_id` (int, optional)<br>`category_id` (int, optional)<br>`speed_limit_bytes` (int, optional)<br>`start_queue` (bool = False)<br>`headers` (dict, optional)<br>`download_page` (str, optional) | `openWorldHint=True`<br>`destructiveHint=False` | Submits an HTTP/HTTPS download task with multi-threaded acceleration. Fails fast if interactive options clash. |
| `abdm_download_hls` | `url` (str - .m3u8)<br>`mode` ("interactive" \| "headless")<br>`filename` (str, optional)<br>`subdirectory` (str, optional)<br>`queue_id` (int, optional)<br>`category_id` (int, optional)<br>`speed_limit_bytes` (int, optional)<br>`start_queue` (bool = False)<br>`headers` (dict, optional)<br>`download_page` (str, optional) | `openWorldHint=True`<br>`destructiveHint=False` | Captures and downloads an HLS (.m3u8) video/audio stream with automatic chunk assembly. |
| `abdm_download_batch` | `urls` (list[str])<br>`mode` ("interactive" \| "headless")<br>`queue_id` (int, optional) | `openWorldHint=True`<br>`destructiveHint=False` | Enqueues up to 50 URLs in a batch with partial success tracking. |
| `abdm_get_queues` | *none* | `readOnlyHint=True` | Fetches configured download queues from ABDM. |
| `abdm_check_status` | *none* | `readOnlyHint=True` | Probes REST reachability, authentication, dynamic port discovery, CLI status, and active capabilities. |
| `abdm_list_downloads` | `status` ("active" \| "paused" \| "completed" \| "error" \| "all") | `readOnlyHint=True` | Lists current downloads reported by ABDM. |
| `abdm_get_download` | `download_id` (str) | `readOnlyHint=True` | Returns status and metadata for a single download task by ID. |
| `abdm_pause` | `download_id` (str \| list[str]) | `idempotentHint=True`<br>`destructiveHint=False` | Pauses one or more active download tasks by ID. |
| `abdm_resume` | `download_id` (str \| list[str]) | `idempotentHint=True`<br>`destructiveHint=False` | Resumes one or more paused download tasks by ID. |
| `abdm_pause_all` | *none* | `idempotentHint=True`<br>`destructiveHint=False` | Pauses all currently active download tasks across ABDM. |
| `abdm_resume_all` | *none* | `idempotentHint=True`<br>`destructiveHint=False` | Resumes all currently paused download tasks across ABDM. |
| `abdm_remove` | `download_id` (str \| list[str])<br>`delete_file` (bool = False) | `destructiveHint=True` | Cancels and removes one or more download tasks. File deletion requires policy opt-in and path verification. |

---

## Architectural Highlights

* **Auto-Wake on Demand**: If the ABDM desktop client is closed when an agent attempts a download or query, `abdm-mcp` automatically launches the GUI via `abdm gui start-if-not-started`.
* **Dynamic Port Auto-Discovery**: Automatically queries the active Ktor integration port via `abdm gui integration show`, preventing failure if ABDM is configured with an alternate port.
* **Resilient ANSI-Safe Parsing**: Mordant color formatting and Unicode/ASCII table borders are safely normalized during CLI state inspection.
* **Zero-Port Setup over Stdio**: Runs seamlessly out of the box via `uvx abdm-mcp` without firewall warnings or localhost port conflicts.

---

## Security & Sandboxing Guardrails

Autonomous agents are powerful, but should not have unrestricted filesystem or network write access. `abdm-mcp` implements defense-in-depth:

1. **Path Sandboxing**: By default, headless downloads are strictly confined to `~/Downloads/ABDM`. Path traversal escapes (`../`) and absolute paths outside allowed roots are rejected.
2. **Private-Network URL Guard**: Protects against SSRF by rejecting direct requests to `localhost`, `127.0.0.0/8`, `::1`, RFC1918 LAN subnets (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), and link-local metadata endpoints (`169.254.169.254`).
3. **Filename Sanitization**: Rejects slashes, drive prefixes, control characters, and reserved Windows device names (`CON`, `PRN`, `AUX`, `NUL`, etc.).
4. **Header Protection**: Blocks sensitive headers (`Cookie`, `Authorization`, `Proxy-Authorization`, `Host`) by default to prevent credential leakage.
5. **Safe Subprocess Execution**: The CLI backend strictly uses `asyncio.create_subprocess_exec` (never `shell=True`) with bounded streaming readers (1MB limit) and hard execution timeouts.

### Environment Variables

| Variable | Default | Description |
| :--- | :--- | :--- |
| `ABDM_CONFIG_DIR` | `~/.abdm` | Custom or portable configuration directory path. |
| `ABDM_PORT` | `15151` | Default port of the ABDM local integration server (overridden by dynamic discovery). |
| `ABDM_API_KEY` | *None* | Optional authentication key configured in ABDM. |
| `ABDM_CLI_PATH` | Auto-detected | Explicit path to `ABDownloadManagerCli` executable. |
| `ABDM_MCP_AUTO_START_APP` | `true` | Automatically wakes the ABDM desktop process on demand if offline. |
| `ABDM_MCP_AUTO_DISCOVER_PORT` | `true` | Queries `abdm gui integration show` to auto-detect the active integration port. |
| `ABDM_MCP_DEFAULT_MODE` | `interactive` | Default mode: `interactive` (GUI confirmation) or `headless` (silent background). |
| `ABDM_MCP_ALLOWED_DOWNLOAD_ROOTS` | `~/Downloads/ABDM` | Comma-separated list of allowed download directories. |
| `ABDM_MCP_ALLOW_PRIVATE_NETWORKS` | `false` | Set to `true` to allow downloads from LAN / private IPs. |
| `ABDM_MCP_ALLOW_SENSITIVE_HEADERS` | `false` | Set to `true` to allow `Cookie` and `Authorization` headers. |
| `ABDM_MCP_ALLOW_FILE_DELETION` | `false` | Set to `true` to permit `abdm_remove(delete_file=True)`. |
| `ABDM_MCP_MAX_BATCH_SIZE` | `50` | Maximum URLs accepted in a single `abdm_download_batch` call. |

---

## Development & Testing

```bash
# Clone the repository
git clone https://github.com/shivamtawari/ab-download-manager-mcp.git
cd ab-download-manager-mcp

# Install dependencies with uv
uv sync --all-groups

# Run full test suite
uv run pytest tests/

# Run linting
uv run ruff check .
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.