JinDaGe - transmission-mcp MCP Details

article

README

🚀 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 安装（推荐）

此方法适用于将该包作为库使用或在不修改代码的情况下运行服务器。

从 PyPI 安装包：

pip install transmission-mcp

在运行应用程序的目录中创建 .env 文件，并添加你的 Transmission URL：

TRANSMISSION_URL=http://localhost:9091

运行 MCP 服务器（默认：标准输入输出）：

python -m transmission_client

本地开发

此方法适用于想要修改源代码的贡献者，使用 uv：

克隆仓库：

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

使用 uv 安装依赖：

uv sync --locked

通过复制示例配置文件并添加你的设置来创建配置文件：

cp .env.example .env

运行 MCP 服务器（默认：标准输入输出）：

uv run -m transmission_client

Docker 安装

此方法使用 Docker 在容器中运行服务器，compose.yaml 包含 Transmission 种子客户端。

克隆仓库（如果尚未克隆）：

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

通过复制示例配置文件并添加你的设置来创建配置文件：

cp .env.example .env

使用 Docker Compose 构建并运行容器（默认端口：8000）：

docker compose up --build -d

查看容器日志：

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 文件。

transmission-mcp