discord-selfbot-mcp 1.2.6 → 1.2.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Microck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,7 +11,7 @@
 <p align="center">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="license">
   <img src="https://img.shields.io/badge/language-python-blue" alt="language">
-  <img src="https://img.shields.io/badge/npm-%40discord--selfbot--mcp-orange" alt="npm">
+  <a href="https://www.npmjs.com/package/discord-selfbot-mcp"><img src="https://img.shields.io/npm/v/discord-selfbot-mcp?color=orange&label=npm" alt="npm"></a>
   <img src="https://img.shields.io/badge/mcp-sdk-orange" alt="mcp">
   <img src="https://img.shields.io/badge/skill-cli-purple" alt="skill">
   <a href="https://github.com/Microck/opencode-studio"><img src="https://img.shields.io/badge/opencode-studio-brown?logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABiElEQVR4nF2Sv0tWcRTGPyeVIpCWwmyJGqQagsqCsL2hhobsD3BvdWhoj/6CiIKaoqXBdMjKRWwQgqZ%2BokSvkIhg9BOT9xPn9Vx79cD3cu6953zP8zznCQB1V0S01d3AKeAKcBVYA94DjyJioru2k9SHE%2Bqc%2Bkd9rL7yf7TUm%2BpQ05yPUM%2Bo626Pp%2BqE2q7GGfWrOpjNnWnAOPAGeAK8Bb4U5D3AJ%2BAQsAAMAHfVvl7gIrAf2Kjiz8BZYB3YC/wFpoGDwHfgEnA0oU7tgHiheEShyXxY/Vn/n6ljye8DcBiYAloRcV3tAdrV1xMRG%2Bo94DywCAwmx33AJHASWK7iiAjzNFOBl7WapPYtYdyo8RlLqVpOVPvq9KoH1NUuOneycaRefqnP1ftdUyiOt5KS%2BqLWdDpVzTXMl5It4Jr6u%2BQ/nhyBc8C7jpowGxGvmxuPqT9qyYuFIKdP71B8WT3SOKexXLrntvqxq3BefaiuFMQ0wqZftxl3M78MjBasfiDN/SAi0kFbtf8ACtKBWZBDoJEAAAAASUVORK5CYII%3D" alt="Add with OpenCode Studio" /></a>
@@ -190,7 +190,7 @@ powered by the robust `discord.py-self` library.
 | **relationships** | 4 | list_friends, send_friend_request, add_friend, remove_friend |
 | **presence** | 2 | set_status, set_activity |
 | **interactions** | 3 | send_slash_command, click_button, select_menu |
-| **threads** | 5 | create_thread, send_thread_message, list_threads, read_thread_messages, archive_thread |
+| **threads** | 5 | create_thread, send_thread_message, list_active_threads, read_thread_messages, archive_thread |
 | **members** | 5 | kick_member, ban_member, unban_member, add_role, remove_role |
 | **invites** | 3 | create_invite, list_invites, delete_invite |
 | **profile** | 1 | edit_profile |
@@ -298,13 +298,13 @@ built-in rate limiting to prevent account bans. configurable via environment var
 
 | variable | default | description |
 |----------|---------|-------------|
-| `RATE_LIMIT_ENABLED` | `false` | Enable/disable rate limiting |
+| `RATE_LIMIT_ENABLED` | `true` | Enable/disable rate limiting |
 | `RATE_LIMIT_MESSAGES_PER_MINUTE` | `10` | Max messages per minute |
 | `RATE_LIMIT_MESSAGES_PER_SECOND` | `1` | Max messages per second |
 | `RATE_LIMIT_ACTIONS_PER_MINUTE` | `5` | Max actions (joins, etc.) per minute |
 | `RATE_LIMIT_COOLDOWN` | `60` | Cooldown duration when limit hit (seconds) |
 
-> **recommended**: Enable rate limiting (`RATE_LIMIT_ENABLED=true`) to reduce ban risk.
+> rate limiting is enabled by default to reduce ban risk. Only disable it if you are deliberately taking responsibility for raw Discord API pacing yourself.
 
 ---
 
@@ -329,11 +329,15 @@ discord_py_self_mcp/
 ├── main.py
 ├── setup.py
 ├── rate_limiter.py
+├── tool_utils.py
+├── cli_runtime.py
+├── logging_utils.py
 ├── captcha/
 │   └── solver.py
 └── tools/
     ├── channels.py
     ├── discrawl.py
+    ├── embed.py
     ├── guilds.py
     ├── interactions.py
     ├── invites.py
@@ -360,7 +364,7 @@ in addition to the mcp server, this package also provides a **skill/cli mode** f
 npm install -g discord-selfbot-mcp
 
 # create .env file
-echo "DISCORD_TOKEN=your_token" > .env
+echo "DISCORD_TOKEN=***" > .env
 
 # use skill mode (from package directory)
 python3 scripts/dcli.py send-message --channel 123 --content "Hello!"
@@ -373,6 +377,8 @@ python3 scripts/dcli.py daemon status    # check daemon status
 python3 scripts/dcli.py send-message --channel CHANNEL_ID --content "Hello"
 python3 scripts/dcli.py list-guilds
 python3 scripts/dcli.py read-messages --channel CHANNEL_ID --limit 20
+python3 scripts/dcli.py get-message-attachments --channel CHANNEL_ID --message MESSAGE_ID
+python3 scripts/dcli.py get-message-attachments --channel CHANNEL_ID --message MESSAGE_ID --download --output-dir ./attachments
 ```
 
 **when to use skill mode**:
@@ -387,4 +393,18 @@ see [SKILL.md](SKILL.md) for detailed documentation.
 
 ### license
 
-mit
+this project is licensed under the [mit license](./LICENSE).
+
+---
+
+### contributing
+
+issues and pull requests are welcome at [github.com/Microck/discord.py-self-mcp](https://github.com/Microck/discord.py-self-mcp).
+
+1. fork the repository
+2. create a feature branch (`git checkout -b feature/my-feature`)
+3. commit your changes (`git commit -m 'add my feature'`)
+4. push to the branch (`git push origin feature/my-feature`)
+5. open a pull request
+
+please ensure tests pass (`pytest`) before submitting.

package/SKILL.md

@@ -123,9 +123,6 @@ python3 scripts/dcli.py pin-message --channel CHANNEL_ID --message MESSAGE_ID
 # Create thread from message (in text channel)
 python3 scripts/dcli.py create-thread --channel CHANNEL_ID --name "Thread Name" --message MESSAGE_ID
 
-# Create standalone thread (in text channel)
-python3 scripts/dcli.py create-thread --channel CHANNEL_ID --name "Thread Name"
-
 # Create thread in forum channel (with initial content)
 python3 scripts/dcli.py create-thread --channel FORUM_CHANNEL_ID --name "Thread Name" --content "Initial post content"
 ```
@@ -176,11 +173,10 @@ python3 scripts/dcli.py read-recent-threads --guild GUILD_ID --within 4 --limit-
 
 #### Get User Info
 ```bash
-# Get current user info
+# Get current user info (supported in daemon mode)
 python3 scripts/dcli.py user-info
 
-# Get specific user info
-python3 scripts/dcli.py user-info --user USER_ID
+# Specific user lookup is not currently supported in daemon mode
 ```
 
 #### List Threads in Channel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discord-selfbot-mcp",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "description": "Discord Selfbot MCP server - Node.js wrapper for Python implementation",
   "main": "index.js",
   "bin": {

package/scripts/daemon.py

@@ -5,6 +5,7 @@ Auto-restart on code change: Enabled
 """
 
 import asyncio
+import base64
 import hashlib
 import json
 import os
@@ -17,8 +18,13 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from secrets import compare_digest
 
+SCRIPT_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = SCRIPT_DIR.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
 env_paths = [
-    Path(__file__).parent.parent / ".env",
+    PROJECT_ROOT / ".env",
     Path.cwd() / ".env",
 ]
 
@@ -29,11 +35,6 @@ for env_path in env_paths:
         load_dotenv(env_path)
         break
 
-TOKEN = os.getenv("DISCORD_TOKEN")
-if not TOKEN:
-    print("Error: DISCORD_TOKEN not found in .env file")
-    sys.exit(1)
-
 import discord
 
 from discord_py_self_mcp.cli_runtime import (
@@ -46,11 +47,11 @@ from discord_py_self_mcp.cli_runtime import (
 )
 from discord_py_self_mcp.logging_utils import log_to_stderr
 from discord_py_self_mcp.tool_utils import NON_MESSAGEABLE_TEXT, validate_message_content
-from discord_py_self_mcp.tools.embed import serialize_message
+from discord_py_self_mcp.tools.embed import serialize_attachment, serialize_message
 
-SCRIPT_DIR = Path(__file__).parent
 DAEMON_SCRIPT = SCRIPT_DIR / "daemon.py"
 CHECK_INTERVAL = 2
+MAX_ATTACHMENT_BYTES_DEFAULT = 10 * 1024 * 1024
 
 
 def _safe_unlink(path: Path) -> None:
@@ -74,6 +75,15 @@ def _load_or_create_auth_token() -> str:
     return token
 
 
+def _get_token_or_exit() -> str:
+    token = os.getenv("DISCORD_TOKEN")
+    if token:
+        return token
+
+    print("Error: DISCORD_TOKEN not found in .env file")
+    raise SystemExit(1)
+
+
 class DiscordDaemon:
     def __init__(self):
         self.client = discord.Client()
@@ -163,6 +173,7 @@ class DiscordDaemon:
 
     async def connect(self):
         """Connect to Discord and wait for the initial ready signal."""
+        token = _get_token_or_exit()
 
         @self.client.event
         async def on_ready():
@@ -173,7 +184,7 @@ class DiscordDaemon:
         async def on_disconnect():
             log_to_stderr(f"[{datetime.now()}] Disconnected from Discord")
 
-        asyncio.create_task(self.client.start(TOKEN))
+        asyncio.create_task(self.client.start(token))
         await asyncio.wait_for(self._connected.wait(), timeout=30)
 
     async def handle_command(self, command_data):
@@ -194,6 +205,14 @@ class DiscordDaemon:
                 return await self._send_message(
                     args.get("channel_id"), args.get("content")
                 )
+            if cmd == "get_message_attachments":
+                return await self._get_message_attachments(
+                    args.get("channel_id"),
+                    args.get("message_id"),
+                    args.get("attachment_index"),
+                    args.get("download_content", False),
+                    args.get("max_bytes", MAX_ATTACHMENT_BYTES_DEFAULT),
+                )
             if cmd == "list_threads":
                 return await self._list_threads(
                     args.get("channel_id"), args.get("archived", False)
@@ -310,6 +329,87 @@ class DiscordDaemon:
         message = await channel.send(content)
         return {"message_id": message.id, "success": True}
 
+    async def _get_message_attachments(
+        self,
+        channel_id,
+        message_id,
+        attachment_index=None,
+        download_content=False,
+        max_bytes=MAX_ATTACHMENT_BYTES_DEFAULT,
+    ):
+        channel = self.client.get_channel(channel_id) or await self.client.fetch_channel(
+            channel_id
+        )
+        if not channel:
+            return {"error": "Channel not found"}
+        if not isinstance(channel, discord.abc.Messageable):
+            return {"error": NON_MESSAGEABLE_TEXT}
+
+        try:
+            message = await channel.fetch_message(message_id)
+        except discord.NotFound:
+            return {"error": "Message not found"}
+        except discord.Forbidden:
+            return {"error": "Access denied to message"}
+
+        attachments = list(message.attachments)
+        if not attachments:
+            return {"error": "Message has no attachments"}
+
+        if attachment_index is not None:
+            if attachment_index < 0 or attachment_index >= len(attachments):
+                return {
+                    "error": (
+                        f"Attachment index {attachment_index} is out of range for "
+                        f"{len(attachments)} attachment(s)"
+                    )
+                }
+            indexed_attachments = [(attachment_index, attachments[attachment_index])]
+        else:
+            indexed_attachments = list(enumerate(attachments))
+
+        result = {
+            "message_id": message.id,
+            "attachments": [
+                {"index": index, **serialize_attachment(attachment)}
+                for index, attachment in indexed_attachments
+            ],
+        }
+
+        if not download_content:
+            return result
+
+        max_bytes = int(max_bytes)
+        downloads = []
+        skipped = []
+        for index, attachment in indexed_attachments:
+            if attachment.size is not None and attachment.size > max_bytes:
+                skipped.append(
+                    {
+                        "index": index,
+                        "filename": attachment.filename,
+                        "reason": f"size={attachment.size} exceeds max_bytes={max_bytes}",
+                    }
+                )
+                continue
+
+            blob = await attachment.read()
+            downloads.append(
+                {
+                    "index": index,
+                    "filename": attachment.filename,
+                    "content_type": attachment.content_type
+                    or "application/octet-stream",
+                    "content_base64": base64.b64encode(blob).decode("ascii"),
+                }
+            )
+
+        if downloads:
+            result["downloads"] = downloads
+        if skipped:
+            result["skipped"] = skipped
+        return result
+
     async def _list_threads(self, channel_id, archived=False):
         channel = self.client.get_channel(channel_id) or await self.client.fetch_channel(
             channel_id

package/scripts/dcli.py

@@ -6,6 +6,7 @@ Commands:
   daemon <start|stop|restart|status>  - Manage daemon process
   send-message --channel ID --content "msg"
   read-messages --channel ID [--limit N] [--after TIME]
+  get-message-attachments --channel ID --message ID [--attachment-index N] [--download --output-dir DIR]
   list-guilds
   list-channels --guild ID
   list-threads --channel ID [--archived]
@@ -28,6 +29,7 @@ Time formats for --after:
   1704067200            - Unix timestamp
 """
 
+import base64
 import json
 import os
 import socket
@@ -36,6 +38,11 @@ import sys
 import time
 from pathlib import Path
 
+SCRIPT_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = SCRIPT_DIR.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
 from discord_py_self_mcp.cli_runtime import AUTH_FILE, PID_FILE, SOCKET_PATH
 
 
@@ -70,8 +77,7 @@ def start_daemon():
     """Auto-start daemon if not running."""
     if not is_daemon_running():
         print("Starting daemon...")
-        script_dir = Path(__file__).parent
-        daemon_script = script_dir / "daemon.py"
+        daemon_script = SCRIPT_DIR / "daemon.py"
         subprocess.Popen(
             [sys.executable, str(daemon_script), "start"],
             stdout=subprocess.DEVNULL,
@@ -170,6 +176,74 @@ def format_messages(messages, reverse=True, use_local_timezone=True):
         print(f"[{created_at}] {author}: {content}")
 
 
+def print_attachment_metadata(attachments):
+    for attachment in attachments:
+        details = [
+            f"[Attachment {attachment.get('index', '?')}] {attachment.get('filename', 'unknown')}"
+        ]
+        if attachment.get("content_type"):
+            details.append(f"type={attachment['content_type']}")
+        if attachment.get("size") is not None:
+            details.append(f"size={attachment['size']}")
+        if attachment.get("width") and attachment.get("height"):
+            details.append(f"dimensions={attachment['width']}x{attachment['height']}")
+        if attachment.get("url"):
+            details.append(f"url={attachment['url']}")
+        print(" ".join(details))
+
+
+def cmd_get_message_attachments(
+    channel_id,
+    message_id,
+    attachment_index=None,
+    download=False,
+    output_dir=None,
+    max_bytes=None,
+):
+    if download and not output_dir:
+        print("Error: --output-dir is required when --download is used")
+        return
+
+    args = {"channel_id": channel_id, "message_id": message_id}
+    if attachment_index is not None:
+        args["attachment_index"] = attachment_index
+    if download:
+        args["download_content"] = True
+    if max_bytes is not None:
+        args["max_bytes"] = max_bytes
+
+    result = send_request({"command": "get_message_attachments", "args": args})
+    if "error" in result:
+        print(f"Error: {result['error']}")
+        return
+
+    attachments = result.get("attachments", [])
+    print(f"Found {len(attachments)} attachment(s) on message {result.get('message_id')}:")
+    print("-" * 60)
+    print_attachment_metadata(attachments)
+
+    skipped = result.get("skipped", [])
+    if skipped:
+        print("\nSkipped downloads:")
+        for item in skipped:
+            print(
+                f"  [Attachment {item.get('index', '?')}] {item.get('filename', 'unknown')}: {item.get('reason', 'Unknown reason')}"
+            )
+
+    downloads = result.get("downloads", [])
+    if not downloads:
+        return
+
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+    print(f"\nSaved downloads to {output_path}:")
+    for item in downloads:
+        filename = item.get("filename") or f"attachment-{item.get('index', 'unknown')}"
+        destination = output_path / f"attachment-{item.get('index', 'unknown')}-{filename}"
+        destination.write_bytes(base64.b64decode(item["content_base64"]))
+        print(f"  {destination}")
+
+
 def cmd_send_message(channel_id, content):
     result = send_request(
         {
@@ -450,8 +524,7 @@ def cmd_create_thread(channel_id, name, message_id, content=None):
 
 
 def cmd_daemon(action):
-    script_dir = Path(__file__).parent
-    daemon_script = script_dir / "daemon.py"
+    daemon_script = SCRIPT_DIR / "daemon.py"
 
     if action == "start":
         if is_daemon_running():
@@ -487,6 +560,16 @@ def main():
     read_parser.add_argument("--limit", "-l", type=int, default=10, help="Number of messages")
     read_parser.add_argument("--after", "-a", type=str, help="Only show messages after this time (e.g. '4h', '30m', '2024-01-01T00:00:00')")
 
+    attachments_parser = subparsers.add_parser(
+        "get-message-attachments", help="Show attachment metadata for a message"
+    )
+    attachments_parser.add_argument("--channel", "-c", required=True, type=int, help="Channel ID")
+    attachments_parser.add_argument("--message", "-m", required=True, type=int, help="Message ID")
+    attachments_parser.add_argument("--attachment-index", type=int, help="Optional zero-based attachment index")
+    attachments_parser.add_argument("--download", action="store_true", help="Download selected attachments to disk")
+    attachments_parser.add_argument("--output-dir", type=str, help="Directory to write downloads into when --download is used")
+    attachments_parser.add_argument("--max-bytes", type=int, help="Skip downloads larger than this many bytes")
+
     subparsers.add_parser("list-guilds", help="List all guilds")
 
     channels_parser = subparsers.add_parser("list-channels", help="List channels in a guild")
@@ -555,6 +638,15 @@ def main():
         cmd_send_message(args.channel, args.content)
     elif args.command == "read-messages":
         cmd_read_messages(args.channel, args.limit, args.after)
+    elif args.command == "get-message-attachments":
+        cmd_get_message_attachments(
+            args.channel,
+            args.message,
+            args.attachment_index,
+            args.download,
+            args.output_dir,
+            args.max_bytes,
+        )
     elif args.command == "list-guilds":
         cmd_list_guilds()
     elif args.command == "list-channels":

package/server.json

@@ -6,14 +6,14 @@
     "url": "https://github.com/Microck/discord.py-self-mcp",
     "source": "github"
   },
-  "version": "1.2.6",
+  "version": "1.2.8",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "discord-selfbot-mcp",
       "runtimeHint": "python",
-      "version": "1.2.6",
+      "version": "1.2.8",
       "packageArguments": [],
       "environmentVariables": [
         {