Transmission MCP

用于传输的Python API包装器和MCP服务器

     

目录

• 特性
• 设置

- 先决条件 - 配置 - 安装 - 从PyPI安装（推荐） - 促进地方发展 -

• 用法

- 作为Python API包装器 - 作为MCP服务器 - 通过MCP客户端 - Windsurf示例

• 贡献

- 发展

• 更新日志
• 许可证

特性

• 的API包装 Transmission torrent客户端使用官方 transmission-rpc 图书馆。
• 用于标准化通信的MCP服务器接口（stdio、sse、流式http）。
• 工具：

- get_session：获取传输会话配置和版本信息。 - 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：验证torrent数据的完整性。 - reannounce_torrent：重新向跟踪器发送洪流。 - move_torrent：将torrent数据移动到新位置。 - set_torrent_labels：为torrent设置标签。 - remove_torrent：删除种子（可选删除数据）。 - delete_torrent：删除torrent及其文件。 - forget_torrent：忘记torrent，保留文件。

设置

先决条件

• 正在运行的实例 传输.（包含在docker compose中）
• Python 3.10+（安装PyPI需要）。
• uv （用于地方发展）

配置

此应用程序需要您的URL Transmission 例子

设置环境变量：复制 .env.example 到 .env 在项目的根目录中，使用您的设置对其进行编辑。应用程序将自动从以下位置加载变量 .env:

• MCP服务器：

- TRANSMISSION_URL：传输实例的URL（默认值： http://localhost:9091). - TRANSMISSION_USER：传输身份验证的用户名（可选）。 - TRANSMISSION_PASS：传输身份验证的密码（可选）。

• 传输实例（用于docker编写设置）：

- TRANSMISSION_DOWNLOAD_DIR：种子下载目录（例如。， /downloads). - TRANSMISSION_WATCH_DIR：torrent文件的监视目录（例如。， /watch). - TRANSMISSION_RPC_URL：传输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). - 检查 传输 其他变量和更多信息。

安装

选择以下安装方法之一。

从PyPI安装（推荐）

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

1. 从PyPI安装软件包：

pip install transmission-mcp

1. 创建一个 .env 运行应用程序并添加应用程序的目录中的文件 Transmission 网址：

TRANSMISSION_URL=http://localhost:9091

1. 运行MCP服务器（默认：stdio）：

python -m transmission_client

促进地方发展

此方法适用于希望修改源代码的贡献者。 使用 uv:

1. 克隆存储库：

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

1. 使用安装依赖项 uv:

uv sync --locked

1. 通过复制示例创建配置文件并添加设置：

cp .env.example .env

1. 运行MCP服务器（默认：stdio）：

uv run -m transmission_client

对于Docker

此方法使用Docker在容器中运行服务器。 compose.yaml包括 传输 torrent客户端。

1. 克隆存储库（如果您还没有）：

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

1. 通过复制示例创建配置文件并添加设置：

cp .env.example .env

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

docker compose up --build -d

1. 访问容器日志：

docker logs transmission-mcp -f

用法

作为Python API包装器

import asyncio
from transmission_client import TransmissionClient

async def main():
    # Initialize client (reads TRANSMISSION_URL, TRANSMISSION_USER, and TRANSMISSION_PASS from env)
    client = TransmissionClient()

    # Use as context manager for automatic cleanup
    async with TransmissionClient() as client:
        # Get session info
        session = await client.get_session()
        print(f"Transmission version: {session['version']}")

        # Get session statistics
        stats = await client.get_session_stats()
        print(f"Download speed: {stats['downloadSpeed']} bytes/s")

        # Check free space
        free_space = await client.free_space("/downloads")
        print(f"Free space: {free_space} bytes")

    # List all torrents
    torrents = await client.list_torrents()

    # Add a torrent
    await client.add_torrent("magnet:?xt=urn:btih:...")

    # Get torrent details
        details = await client.get_torrent("1")  # Use ID or hash

    # Control torrents
        await client.stop_torrent("1")  # Pause
        await client.start_torrent("1")  # Resume

        # Verify torrent data
        await client.verify_torrent("1")

        # Move torrent data
        await client.move_torrent("1", "/new/location", move=True)

        # Set torrent labels
        await client.set_torrent_labels("1", ["movies", "4k"])

        # Remove torrent (keep files)
        await client.remove_torrent("1", delete_data=False)

        # Delete torrent and files
        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', or 'streamable-http'

通过MCP客户端

适用于任何兼容MCP的客户端。可用工具：

• get_session：获取传输会话配置和版本信息。
• 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或哈希验证torrent数据的完整性。
• reannounce_torrent：通过ID或哈希将torrent重新通知给跟踪器。
• move_torrent：通过ID或哈希将torrent数据移动到新位置。
• set_torrent_labels：按ID或哈希为种子设置标签。
• remove_torrent：按ID或哈希删除种子（可选删除数据）。
• delete_torrent：按ID或哈希删除torrent及其文件。
• forget_torrent：忘记torrent，按ID或哈希保存文件。

Windsurf示例

配置：

{
  "mcpServers": {
    ...
    # with stdio (only requires uv)
    "transmission-mcp": {
      "command": "uvx",
      "args": [ "transmission-mcp" ],
      "env": {
        "TRANSMISSION_URL": "http://localhost:9091", # (Optional) Default Transmission instance URL
        "TRANSMISSION_USER": "username", # (Optional) Transmission username
        "TRANSMISSION_PASS": "password" # (Optional) Transmission password
      }
    },
    # with docker (only requires 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" ]
    },
    # with sse transport (requires installation)
    "transmission-mcp": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    },
    # with streamable-http transport (requires installation)
    "transmission-mcp": {
      "serverUrl": "http://127.0.0.1:8000/mcp"
    },
    ...
  }
}

更新日志

看 更改日志.md 查看此项目的更改历史。

贡献

欢迎投稿！请打开问题或提交拉取请求。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。