discord-selfbot-mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,139 +1,255 @@
 <p align="center">
-  <img src="./logo.png" alt="discord-selfbot-mcp" width="100">
+  <img src="./logo.png" alt="discord-py-self-mcp" width="100">
 </p>
 
-<h1 align="center">discord-selfbot-mcp</h1>
+<h1 align="center">discord-py-self-mcp</h1>
 
 <p align="center">
-  comprehensive discord selfbot mcp server with 60+ tools for full user autonomy
+  comprehensive discord selfbot mcp server for full user autonomy.
 </p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="license">
-  <img src="https://img.shields.io/badge/language-typescript-blue" alt="language">
+  <img src="https://img.shields.io/badge/language-python-blue" alt="language">
   <img src="https://img.shields.io/badge/mcp-sdk-orange" alt="mcp">
+  <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>
 </p>
 
+
 ---
+### overview
 
-### quickstart
+discord-py-self-mcp acts as a bridge between your AI assistant (Claude Code, Opencode, Codex, etc) and your personal Discord account. unlike standard bots, this "selfbot" runs as you; allowing your AI to read your DMs, reply to friends, manage your servers, and interact with buttons/menus just like a human user.
 
-automatic setup wizard (extracts token via browser):
+built on the <a href="https://github.com/dolfies/discord.py-self">discord.py-self</a> library by dolfies. it offers a safe, stable, and feature-rich interface for automating your daily discord life.
 
-```bash
-npx discord-selfbot-mcp-setup
+> **note**: automating user accounts is against the Discord ToS. use this at your own risk.
+
+---
+
+### quick installation
+
+**codex**  
+tell codex:  
 ```
+Fetch and follow instructions from https://raw.githubusercontent.com/Microck/discord.py-self-mcp/refs/heads/master/.codex/INSTALL.md
+```
+
+**opencode**  
+tell opencode:  
+```
+Fetch and follow instructions from https://raw.githubusercontent.com/Microck/discord.py-self-mcp/refs/heads/master/.opencode/INSTALL.md
+```
+
+---
+
+### manual installation
+
+**prerequisites**:
+- python 3.10+
+- `uv` (recommended) or `pip`
+- **voice support (linux only)**: `libffi-dev` (or `libffi-devel`), `python-dev` (e.g. `python3-dev`)
 
-manual installation:
+**install**:
 
 ```bash
-npm install -g discord-selfbot-mcp
+uv tool install git+https://github.com/Microck/discord.py-self-mcp.git
+# or
+pip install git+https://github.com/Microck/discord.py-self-mcp.git
 ```
 
+> **note**: voice dependencies (PyNaCl) are included by default. on linux, ensure system packages are installed first.
+
+---
+
+### npm installation (node.js wrapper)
+
+**prerequisites**:
+- node.js 18+
+- python 3.10+
+- the npm wrapper automatically detects if python package is installed
+
+**install**:
+
+```bash
+npm install -g discord-selfbot-mcp
+```
+
+the npm package is a wrapper that uses the underlying python implementation. if python package is not installed, npm will guide you through installation.
+
+---
+
+### how it works (setup wizard)
+
+run the interactive setup script to generate your config:
+
+```bash
+# if using npm
+discord-selfbot-mcp-setup
+
+# if using uv
+uv tool run discord-py-self-mcp-setup
+
+# or running the script directly from the repo
+python3 discord_py_self_mcp/setup.py
+```
+
+1. **extract token**: automatically grabs your token from an open browser session (playwright)
+2. **generate config**: outputs the mcp configuration json for you
+3. **configure**: paste the config into your mcp client settings
+
+---
+
+### manual configuration
+
+**using npm**:
+
+```json
+{
+  "mcpServers": {
+    "discord-py-self": {
+      "command": "discord-selfbot-mcp",
+      "env": {
+        "DISCORD_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+**using python (pip/uv)**:
+
+```json
+{
+  "mcpServers": {
+    "discord-py-self": {
+      "command": "uv",
+      "args": ["tool", "run", "discord-py-self-mcp"],
+      "env": {
+        "DISCORD_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+if installed via pip/venv, adjust the command to point to your python executable or script location.
+
+---
+
 ### features
 
-**60 tools** across 14 categories.
+powered by the robust `discord.py-self` library.
 
 | category | tools | description |
 |----------|-------|-------------|
-| **system** | 3 | health, whoami, get_config |
-| **guilds** | 8 | list, info, members, nickname, leave, invite, create, delete |
-| **channels** | 5 | list, info, create, delete, edit |
-| **messages** | 8 | read, send, reply, edit, delete, search, get, forward |
-| **reactions** | 4 | react, unreact, get_reactions, remove_all |
-| **pins** | 3 | pin, unpin, list_pinned |
-| **dms** | 5 | list, read, send, create, close |
-| **threads** | 7 | list, create, join, leave, archive, read, send |
-| **presence** | 5 | set_status, set_custom, set_activity, clear, get_user |
-| **voice** | 5 | join, leave, set_state, get_state, list_members |
-| **relationships** | 8 | friends, blocked, pending, request, remove, block, unblock, accept |
-| **notifications** | 5 | mentions, mark_read, mark_guild_read, mute_channel, mute_guild |
-| **files** | 3 | upload, download, list |
-| **events** | 4 | list, get, rsvp, create |
-| **profile** | 1 | edit_profile (avatar, bio, username) |
-| **interactions** | 1 | trigger_typing |
-| **invites** | 1 | accept_invite |
+| **system** | 2 | get_user_info, list_guilds |
+| **messages** | 5 | send_message, read_messages, search_messages, edit_message, delete_message, pin/unpin |
+| **channels** | 3 | create_channel, delete_channel, list_channels |
+| **voice** | 2 | join_voice_channel, leave_voice_channel |
+| **relationships** | 4 | list_friends, add_friend, remove_friend, send_friend_request |
+| **presence** | 2 | set_status, set_activity |
+| **interactions** | 3 | send_slash_command, click_button, select_menu |
+| **threads** | 2 | create_thread, archive_thread |
+| **members** | 4 | kick_member, ban_member, unban_member, add_role, remove_role |
+| **invites** | 3 | create_invite, list_invites, delete_invite |
+| **profile** | 1 | edit_profile (bio, accent) |
+| **reactions** | 2 | add_reaction, remove_reaction |
 
 ### comparison
 
-| feature | discord-selfbot-mcp | Maol-1997 | codebyyassine | elyxlz |
-|---------|---------------------|-----------|---------------|--------|
-| read messages | ✅ | ✅ | ✅ | ✅ |
-| send messages | ✅ | ✅ | ✅ | ✅ |
-| list guilds | ✅ | ✅ | ✅ | ✅ |
-| list channels | ✅ | ✅ | ✅ | ✅ |
-| get user info | ✅ | ✅ | ✅ | ❌ |
-| search messages | ✅ | ❌ | ❌ | ❌ |
-| create channels | ✅ | ❌ | ✅ | ❌ |
-| delete channels | ✅ | ❌ | ✅ | ❌ |
-| edit messages | ✅ | ❌ | ❌ | ❌ |
-| delete messages | ✅ | ❌ | ❌ | ❌ |
-| join voice | ✅ | ❌ | ❌ | ❌ |
-| manage friends | ✅ | ❌ | ❌ | ❌ |
-| manage threads | ✅ | ❌ | ❌ | ❌ |
-| setup wizard | ✅ | ❌ | ❌ | ❌ |
-| **total tools** | **60** | **7** | **29** | **4** |
-
-### usage
-
-run manually (requires token):
+| feature | discord-py-self-mcp | discord.py-self (Lib) | Maol-1997 | codebyyassine | elyxlz |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| **read messages** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **send messages** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **list guilds** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **list channels** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **get user info** | ✅ | ✅ | ✅ | ✅ | ❌ |
+| **search messages** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **create channels** | ✅ | ✅ | ❌ | ✅ | ❌ |
+| **delete channels** | ✅ | ✅ | ❌ | ✅ | ❌ |
+| **edit messages** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **delete messages** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **join voice** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **manage friends** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **manage threads** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **slash commands** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **click buttons** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **select menus** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **kick/ban** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **invites** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **profile edit** | ✅ | ✅ | ❌ | ❌ | ❌ |
+| **setup wizard** | ✅ | ❌ | ❌ | ❌ | ❌ |
+| **captcha solver** | ✅ | ❌ | ❌ | ❌ | ❌ |
 
-```bash
-export DISCORD_TOKEN='your_token'
-npx discord-selfbot-mcp
-```
+✅ = supported
 
-configure in claude/opencode:
+❌ = not supported
 
-```json
-{
-  "mcpServers": {
-    "discord-selfbot": {
-      "command": "npx",
-      "args": ["discord-selfbot-mcp"],
-      "env": {
-        "DISCORD_TOKEN": "your_token"
-      }
-    }
-  }
-}
-```
+🚧 = planned / in progress
 
-### project structure
 
-```bash
-src/
-├── core/           # configuration, logging, errors
-├── discord/        # discord.js client wrapper
-├── mcp/            # mcp server & registry
-├── tools/          # tool implementations
-│   ├── channels/
-│   ├── dms/
-│   ├── events/
-│   ├── files/
-│   ├── guilds/
-│   ├── interactions/
-│   ├── invites/
-│   ├── messages/
-│   ├── notifications/
-│   ├── presence/
-│   ├── profile/
-│   ├── relationships/
-│   ├── system/
-│   ├── threads/
-│   └── voice/
-├── index.ts        # entry point
-└── setup.ts        # setup wizard
+---
+
+### captcha solving (experimental)
+
+automatically solves hCaptchas when encountered (e.g., joining servers, DMs).
+built upon [ScremerMemer/hCaptcha-Solver](https://github.com/ScremerMemer/hCaptcha-Solver).
+
+> **warning**: this feature is experimental. use at your own risk.
+
+**requirements:**
+1. **Groq API Key**: required for AI vision. set `GROQ_API_KEY` in environment.
+2. **Camoufox**: required for browser fingerprinting.
+   ```bash
+   pip install camoufox[geoip]
+   python -m camoufox fetch
+   ```
+
+**configuration:**
+add to your environment variables:
+```json
+"GROQ_API_KEY": "gsk_..."
 ```
 
+---
+
 ### troubleshooting
 
 | problem | solution |
 |---------|----------|
-| **token invalid** | run `npx discord-selfbot-mcp-setup` to extract a fresh one |
-| **rate limited** | reduce `RATE_LIMIT_CONCURRENCY` env var (default: 3) |
-| **missing permissions** | ensure account has access to the guild/channel |
-| **verification required** | solve captcha/2fa in browser during setup |
+| **token invalid** | run the setup script again to extract a fresh one |
+| **missing dependencies** | ensure `uv` or `pip` installed all requirements (`discord.py-self`, `mcp`, `playwright`) |
+| **playwright error** | run `playwright install chromium` |
+| **audioop error** | ensure `audioop-lts` is installed if using python 3.13+ |
+| **voice error** | install `libffi-dev` (linux) or ensure PyNaCl built correctly |
+
+---
+
+### project structure
+
+```
+discord_py_self_mcp/
+├── bot.py          # discord.py-self client instance
+├── main.py         # mcp server entry point
+├── setup.py        # setup wizard (token extraction)
+└── tools/          # tool implementations
+    ├── channels.py
+    ├── guilds.py
+    ├── interactions.py
+    ├── invites.py
+    ├── members.py
+    ├── messages.py
+    ├── presence.py
+    ├── profile.py
+    ├── reactions.py
+    ├── registry.py
+    ├── relationships.py
+    ├── threads.py
+    └── voice.py
+```
+
+---
 
 ### license
 

package/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+function findPython() {
+  const possibleCommands = ['python3', 'python', 'python3.10', 'python3.11', 'python3.12'];
+  for (const cmd of possibleCommands) {
+    try {
+      const result = spawn.sync(cmd, ['--version'], { stdio: 'ignore' });
+      if (result.status === 0) {
+        return cmd;
+      }
+    } catch (e) {
+    }
+  }
+  return null;
+}
+
+function checkPythonPackage(pythonCmd) {
+  try {
+    const result = spawn.sync(
+      pythonCmd,
+      ['-c', 'import discord_py_self_mcp'],
+      { stdio: 'ignore' }
+    );
+    return result.status === 0;
+  } catch (e) {
+    return false;
+  }
+}
+
+async function main() {
+  const pythonCmd = findPython();
+
+  if (!pythonCmd) {
+    console.error('Error: Python 3.10+ not found. Please install Python 3.10 or higher.');
+    process.exit(1);
+  }
+
+  if (!checkPythonPackage(pythonCmd)) {
+    console.error('Error: discord-py-self-mcp Python package not installed.');
+    console.error('Run: pip install git+https://github.com/Microck/discord.py-self-mcp.git');
+    console.error('Or: uv tool install git+https://github.com/Microck/discord.py-self-mcp.git');
+    process.exit(1);
+  }
+
+  const pythonScript = spawn.sync(
+    pythonCmd,
+    ['-c', 'import discord_py_self_mcp.main as m; print(m.__file__)'],
+    { encoding: 'utf-8' }
+  );
+
+  if (pythonScript.stderr && pythonScript.stderr.includes('ModuleNotFoundError')) {
+    console.error('Error: discord-py-self-mcp not found. Install it first.');
+    console.error('pip install git+https://github.com/Microck/discord.py-self-mcp.git');
+    process.exit(1);
+  }
+
+  const mainPath = pythonScript.stdout.trim();
+  const mainDir = path.dirname(mainPath);
+
+  const proc = spawn(pythonCmd, ['-m', 'discord_py_self_mcp.main'], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      PATH: process.env.PATH
+    }
+  });
+
+  proc.on('error', (err) => {
+    console.error('Failed to start Python MCP server:', err.message);
+    process.exit(1);
+  });
+
+  proc.on('exit', (code) => {
+    process.exit(code ?? 0);
+  });
+
+  process.on('SIGTERM', () => proc.kill('SIGTERM'));
+  process.on('SIGINT', () => proc.kill('SIGINT'));
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/package.json

@@ -1,48 +1,38 @@
 {
   "name": "discord-selfbot-mcp",
-  "version": "1.0.0",
-  "description": "Comprehensive Discord Selfbot MCP Server with 50+ tools for full Discord user functionality",
-  "type": "module",
-  "main": "dist/index.js",
+  "version": "1.0.2",
+  "description": "Discord Selfbot MCP server - Node.js wrapper for Python implementation",
+  "main": "index.js",
   "bin": {
-    "discord-selfbot-mcp": "./dist/index.js",
-    "discord-selfbot-mcp-setup": "./dist/setup.js"
+    "discord-selfbot-mcp": "index.js",
+    "discord-selfbot-mcp-setup": "setup-wizard.js"
   },
   "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts",
-    "start": "node dist/index.js",
-    "setup": "tsx src/setup.ts",
-    "lint": "eslint src/",
-    "typecheck": "tsc --noEmit"
+    "postinstall": "node scripts/postinstall.js"
   },
+  "files": [
+    "index.js",
+    "setup-wizard.js",
+    "scripts/postinstall.js"
+  ],
   "keywords": [
+    "mcp",
     "discord",
     "selfbot",
-    "mcp",
     "model-context-protocol",
     "ai",
     "automation"
   ],
-  "author": "",
+  "author": "Microck",
   "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "discord.js-selfbot-v13": "^3.4.1",
-    "playwright": "^1.57.0",
-    "zod": "^3.24.1",
-    "zod-to-json-schema": "^3.25.1"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Microck/discord.py-self-mcp.git"
   },
-  "devDependencies": {
-    "@types/node": "^22.10.5",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+  "dependencies": {
+    "playwright": "^1.40.0"
   },
   "engines": {
     "node": ">=18.0.0"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ]
+  }
 }

package/scripts/postinstall.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('child_process');
+
+function findPython() {
+  const possibleCommands = ['python3', 'python', 'python3.10', 'python3.11', 'python3.12'];
+  for (const cmd of possibleCommands) {
+    const result = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
+    if (result.status === 0) {
+      return cmd;
+    }
+  }
+  return null;
+}
+
+const pythonCmd = findPython();
+
+if (!pythonCmd) {
+  console.warn('⚠️  Warning: Python 3.10+ not found.');
+  console.warn('   Please install Python 3.10 or higher to use this package.');
+  console.warn('   https://www.python.org/downloads/');
+  process.exit(0);
+}
+
+const packageCheck = spawnSync(
+  pythonCmd,
+  ['-c', 'import discord_py_self_mcp'],
+  { stdio: 'pipe' }
+);
+
+if (packageCheck.status !== 0) {
+  console.warn('⚠️  Warning: discord-py-self-mcp Python package not installed.');
+  console.warn('');
+  console.warn('   To install, run one of the following:');
+  console.warn('');
+  console.warn('   Using pip:');
+  console.warn('     pip install git+https://github.com/Microck/discord.py-self-mcp.git');
+  console.warn('');
+  console.warn('   Using uv (recommended):');
+  console.warn('     uv tool install git+https://github.com/Microck/discord.py-self-mcp.git');
+  console.warn('');
+  console.warn('   Or install manually:');
+  console.warn('     git clone https://github.com/Microck/discord.py-self-mcp.git');
+  console.warn('     cd discord.py-self-mcp');
+  console.warn('     pip install -e .');
+  console.warn('');
+}
+
+console.log('✅ discord-selfbot-mcp npm package installed successfully!');

package/setup-wizard.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+const { chromium } = require('playwright');
+const readline = require('readline');
+const path = require('path');
+
+const DISCORD_URL = 'https://discord.com/login';
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+function question(prompt) {
+  return new Promise(resolve => rl.question(prompt, resolve));
+}
+
+async function getTokenFromBrowser() {
+  console.log('Opening browser...');
+
+  const browser = await chromium.launch({
+    headless: false,
+    args: ['--disable-blink-features=AutomationControlled']
+  });
+
+  const context = await browser.newContext({
+    viewport: { width: 1280, height: 800 },
+    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+  });
+
+  const page = await context.newPage();
+  await page.goto(DISCORD_URL);
+
+  console.log('Please log in to Discord in the opened browser window.');
+  console.log('The script will automatically detect your token once you are logged in.');
+
+  let token = null;
+  while (!token) {
+    try {
+      token = await page.evaluate(`
+        (webpackChunkdiscord_app.push([[],{},e=>{m=[];for(let c in e.c)m.push(e.c[c])}]),m).find(m=>m?.exports?.default?.getToken).exports.default.getToken()
+      `);
+      if (token) {
+        break;
+      }
+    } catch (e) {
+    }
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+
+  console.log(`Token found: ${token.substring(0, 20)}...${token.substring(token.length - 5)}`);
+  await browser.close();
+  return token;
+}
+
+function generateConfig(token) {
+  return {
+    mcpServers: {
+      'discord-selfbot': {
+        command: 'discord-selfbot-mcp',
+        env: {
+          DISCORD_TOKEN: token
+        }
+      }
+    }
+  };
+}
+
+async function main() {
+  console.log('=== Discord Selfbot MCP Setup ===');
+  console.log('1. Extract token automatically (browser)');
+  console.log('2. Enter token manually');
+
+  const choice = await question('Choice (1/2): ');
+
+  let token = null;
+  if (choice === '1') {
+    token = await getTokenFromBrowser();
+  } else {
+    token = await question('Enter your Discord token: ');
+  }
+
+  if (!token) {
+    console.log('No token provided.');
+    rl.close();
+    process.exit(1);
+  }
+
+  console.log('\nGenerated MCP Configuration:');
+  console.log(JSON.stringify(generateConfig(token), null, 2));
+
+  const save = await question('\nSave to mcp.json? (y/n): ');
+  if (save.toLowerCase() === 'y') {
+    const fs = require('fs');
+    fs.writeFileSync('mcp.json', JSON.stringify(generateConfig(token), null, 2));
+    console.log('Saved to mcp.json');
+  }
+
+  rl.close();
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  rl.close();
+  process.exit(1);
+});