Transmission MCP

🚀 Transmission的Python API包裝器與MCP服務器

本倉庫提供了一個基於 transmission-rpc 庫的 Transmission 種子客戶端的Python API包裝器和MCP（模型上下文協議）服務器，方便集成到其他應用程序或服務中。

🚀 快速開始

本項目是一個為 Transmission 種子客戶端打造的工具，提供了 Python API 包裝器和 MCP 服務器，可輕鬆集成到其他應用或服務中。以下將詳細介紹項目的特性、設置、安裝、使用等方面的內容。

✨ 主要特性

• 使用官方 transmission-rpc 庫為 Transmission 種子客戶端提供 API 包裝器。
• 提供 MCP 服務器接口，支持標準化通信（標準輸入輸出、服務器發送事件、可流式傳輸的 HTTP）。
• 提供以下工具：
  • get_session：獲取 Transmission 會話配置和版本信息。
  • get_session_stats：獲取會話統計信息（速度、種子數量、累積統計數據）。
  • free_space：獲取指定路徑下的可用磁盤空間（以字節為單位）。
  • list_torrents：列出所有種子及其詳細信息。
  • get_torrent_details：獲取特定種子的詳細信息。
  • get_torrent_stats：獲取特定種子的統計信息/狀態。
  • get_recently_active：獲取最近活躍的種子以及最近刪除的種子的 ID。
  • add_torrent：從磁力鏈接、HTTP URL 或本地文件下載種子。
  • download_torrent：從磁力鏈接、HTTP URL 或本地文件下載種子。
  • start_torrent：啟動（恢復）種子。
  • stop_torrent：停止（暫停）種子。
  • pause_torrent：暫停種子。
  • verify_torrent：驗證種子數據的完整性。
  • reannounce_torrent：向追蹤器重新宣告種子。
  • move_torrent：將種子數據移動到新位置。
  • set_torrent_labels：為種子設置標籤。
  • remove_torrent：移除種子（可選擇刪除數據）。
  • delete_torrent：刪除種子及其文件。
  • forget_torrent：忘記種子，保留文件。

📦 安裝指南

前提條件

• 運行中的 Transmission 實例（包含在 Docker Compose 中）。
• Python 3.10 及以上版本（PyPI 安裝所需）。
• uv（用於本地開發）

配置

本應用程序需要 Transmission 實例的 URL。

設置環境變量：將 .env.example 複製到項目根目錄下的 .env 文件，並根據你的設置進行編輯。應用程序將自動從 .env 文件中加載變量：

• MCP 服務器：
  • TRANSMISSION_URL：Transmission 實例的 URL（默認：http://localhost:9091）。
  • TRANSMISSION_USER：Transmission 認證的用戶名（可選）。
  • TRANSMISSION_PASS：Transmission 認證的密碼（可選）。
• Transmission 實例（用於 Docker Compose 設置）：
  • TRANSMISSION_DOWNLOAD_DIR：種子下載目錄（例如：/downloads）。
  • TRANSMISSION_WATCH_DIR：種子文件監視目錄（例如：/watch）。
  • TRANSMISSION_RPC_URL：Transmission API 的 RPC URL（例如：http://localhost:9091/transmission/rpc）。
  • TRANSMISSION_PEER_PORT：BitTorrent 連接的對等端口（例如：51413）。
  • TRANSMISSION_SPEED_LIMIT_DOWN：下載速度限制（KB/s，例如：100）。
  • TRANSMISSION_SPEED_LIMIT_UP：上傳速度限制（KB/s，例如：100）。 更多變量和信息請參考 Transmission。

安裝方式

選擇以下安裝方法之一：

從 PyPI 安裝（推薦）

此方法適用於將該包作為庫使用或在不修改代碼的情況下運行服務器。

1. 從 PyPI 安裝包：

pip install transmission-mcp

2. 在運行應用程序的目錄中創建 .env 文件，並添加你的 Transmission URL：

TRANSMISSION_URL=http://localhost:9091

3. 運行 MCP 服務器（默認：標準輸入輸出）：

python -m transmission_client

本地開發

此方法適用於想要修改源代碼的貢獻者，使用 uv：

1. 克隆倉庫：

git clone https://github.com/philogicae/transmission-mcp.git
cd transmission-mcp

2. 使用 uv 安裝依賴：

uv sync --locked

3. 通過複製示例配置文件並添加你的設置來創建配置文件：

cp .env.example .env

4. 運行 MCP 服務器（默認：標準輸入輸出）：

uv run -m transmission_client

Docker 安裝

此方法使用 Docker 在容器中運行服務器，compose.yaml 包含 Transmission 種子客戶端。

1. 克隆倉庫（如果尚未克隆）：

git clone https://github.com/philogicae/transmission-mcp.git
cd transmission-mcp

2. 通過複製示例配置文件並添加你的設置來創建配置文件：

cp .env.example .env

3. 使用 Docker Compose 構建並運行容器（默認端口：8000）：

docker compose up --build -d

4. 查看容器日誌：

docker logs transmission-mcp -f

💻 使用示例

作為 Python API 包裝器

import asyncio
from transmission_client import TransmissionClient

async def main():
    # 初始化客戶端（從環境變量中讀取 TRANSMISSION_URL、TRANSMISSION_USER 和 TRANSMISSION_PASS）
    client = TransmissionClient()

    # 使用上下文管理器進行自動清理
    async with TransmissionClient() as client:
        # 獲取會話信息
        session = await client.get_session()
        print(f"Transmission 版本: {session['version']}")

        # 獲取會話統計信息
        stats = await client.get_session_stats()
        print(f"下載速度: {stats['downloadSpeed']} 字節/秒")

        # 檢查可用空間
        free_space = await client.free_space("/downloads")
        print(f"可用空間: {free_space} 字節")

    # 列出所有種子
    torrents = await client.list_torrents()

    # 添加種子
    await client.add_torrent("magnet:?xt=urn:btih:...")

    # 獲取種子詳細信息
    details = await client.get_torrent("1")  # 使用 ID 或哈希值

    # 控制種子
    await client.stop_torrent("1")  # 暫停
    await client.start_torrent("1")  # 恢復

    # 驗證種子數據
    await client.verify_torrent("1")

    # 移動種子數據
    await client.move_torrent("1", "/new/location", move=True)

    # 設置種子標籤
    await client.set_torrent_labels("1", ["movies", "4k"])

    # 移除種子（保留文件）
    await client.remove_torrent("1", delete_data=False)

    # 刪除種子及其文件
    await client.remove_torrent("1", delete_data=True)

if __name__ == "__main__":
    asyncio.run(main())

作為 MCP 服務器

from transmission_client import TransmissionMCP

TransmissionMCP.run(transport="sse") # 'stdio', 'sse', 或 'streamable-http'

通過 MCP 客戶端

可與任何兼容 MCP 的客戶端一起使用，可用工具如下：

• get_session：獲取 Transmission 會話配置和版本信息。
• get_session_stats：獲取會話統計信息（速度、種子數量、累積統計數據）。
• free_space：獲取指定路徑下的可用磁盤空間（以字節為單位）。
• list_torrents：列出所有種子及其詳細信息。
• get_torrent_details：通過 ID 或哈希值獲取特定種子的詳細信息。
• get_torrent_stats：通過 ID 或哈希值獲取特定種子的統計信息/狀態。
• get_recently_active：獲取最近活躍的種子以及最近刪除的種子的 ID。
• add_torrent：從磁力鏈接、HTTP URL 或本地文件路徑添加種子。
• download_torrent：通過磁力鏈接、HTTP URL 或本地文件下載種子。
• start_torrent：通過 ID 或哈希值啟動（恢復）種子。
• stop_torrent：通過 ID 或哈希值停止（暫停）種子。
• pause_torrent：通過 ID 或哈希值暫停種子。
• verify_torrent：通過 ID 或哈希值驗證種子數據的完整性。
• reannounce_torrent：通過 ID 或哈希值向追蹤器重新宣告種子。
• move_torrent：通過 ID 或哈希值將種子數據移動到新位置。
• set_torrent_labels：通過 ID 或哈希值為種子設置標籤。
• remove_torrent：通過 ID 或哈希值移除種子（可選擇刪除數據）。
• delete_torrent：通過 ID 或哈希值刪除種子及其文件。
• forget_torrent：通過 ID 或哈希值忘記種子，保留文件。

使用 Windsurf 的示例

配置如下：

{
  "mcpServers": {
    ...
    # 使用標準輸入輸出（僅需 uv）
    "transmission-mcp": {
      "command": "uvx",
      "args": [ "transmission-mcp" ],
      "env": {
        "TRANSMISSION_URL": "http://localhost:9091", # （可選）默認 Transmission 實例 URL
        "TRANSMISSION_USER": "username", # （可選）Transmission 用戶名
        "TRANSMISSION_PASS": "password" # （可選）Transmission 密碼
      }
    },
    # 使用 Docker（僅需 Docker）
    "transmission-mcp": {
      "command": "docker",
      "args": [ "run", "-i", "-p", "8000:8000", "-e", "TRANSMISSION_URL=http://localhost:9091", "-e", "TRANSMISSION_USER=username", "-e", "TRANSMISSION_PASS=password", "philogicae/transmission-mcp:latest", "transmission-mcp" ]
    },
    # 使用 SSE 傳輸（需要安裝）
    "transmission-mcp": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    },
    # 使用可流式傳輸的 HTTP 傳輸（需要安裝）
    "transmission-mcp": {
      "serverUrl": "http://127.0.0.1:8000/mcp"
    },
    ...
  }
}

📚 詳細文檔

變更日誌

有關本項目的變更歷史，請參閱 CHANGELOG.md。

貢獻

歡迎貢獻代碼！請提交問題或拉取請求。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。