![\"discord-py-self-mcp\"](\"./logo.png\"){kind=logo}
\n\n \n
\n comprehensive discord selfbot mcp server for full user autonomy.\n
\n\n\n ![\"release\"](\"https://img.shields.io/github/v/release/Microck/discord.py-self-mcp?display_name=tag&style=flat-square&label=release&color=000000\")
\n
![\"license\"](\"https://img.shields.io/badge/license-mit-000000?style=flat-square\"){kind=icon}
\n\n
\n\n---\n\n## quick start\n\nthis is a local mcp server (stdio transport). your mcp client spawns it as a process, and you provide secrets (like `DISCORD_TOKEN`) via the client's `env`/`environment` config.\n\nmanual run:\n\n```bash\nDISCORD_TOKEN=\"your_discord_token_here\" python3 -m discord_py_self_mcp.main\n```\n\n> **important:** automating user accounts is against the Discord ToS. use this at your own risk.\n\n---\n\n### overview\n\ndiscord-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.\n\nbuilt on the discord.py-self library by dolfies.\n\n---\n\n### quick installation\n\npaste this into your llm agent session:\n\n```\nInstall and configure discord-selfbot-mcp by following the instructions here:\nhttps://raw.githubusercontent.com/Microck/discord.py-self-mcp/refs/heads/master/INSTALL.md\n```\n\n**npm (recommended)**\n\n```bash\nnpm install -g discord-selfbot-mcp\ndiscord-selfbot-mcp-setup\n```\n\n---\n\n### manual installation\n\n**prerequisites**:\n- python 3.10+\n- `uv` (recommended) or `pip`\n- **voice support (linux only)**: `libffi-dev` (or `libffi-devel`), `python-dev` (e.g. `python3-dev`)\n\n**install**:\n\n```bash\nuv tool install git+https://github.com/Microck/discord.py-self-mcp.git\n# or\npip install git+https://github.com/Microck/discord.py-self-mcp.git\n```\n\n> **note**: voice dependencies (PyNaCl) are included by default. on linux, ensure system packages are installed first.\n\n---\n\n### npm installation (node.js wrapper)\n\n**prerequisites**:\n- node.js 18+\n- python 3.10+\n\n**install**:\n\n```bash\nnpm install -g discord-selfbot-mcp\n```\n\nthe npm package is a wrapper that uses the underlying python implementation.\n\n---\n\n### how it works (setup wizard)\n\nrun the interactive setup script to extract your token and generate the mcp config json (it can also write to common client config files and creates a backup before editing).\n\n```bash\n# if using npm\ndiscord-selfbot-mcp-setup\n\n# if using python (uv/pip)\npython3 -m discord_py_self_mcp.setup\n```\n\n1. **extract token**: grabs your token from an open browser session (playwright) or via manual entry\n2. **generate config**: prints the mcp configuration json (and can write it to your client config)\n3. **configure**: paste the config into your mcp client settings\n\n---\n\n### manual configuration\n\nfor the default `stdio` transport, configure the server as a local command and pass the token via `env` (not `url`/`headers`).\n\nexamples:\n- `mcp.example.json`\n- `mcp.python.example.json`\n- `.env.example`\n\n**npm wrapper (recommended)**:\n\n```json\n{\n \"mcpServers\": {\n \"discord-py-self\": {\n \"command\": \"discord-selfbot-mcp\",\n \"env\": {\n \"DISCORD_TOKEN\": \"${DISCORD_TOKEN}\"\n }\n }\n }\n}\n```\n\n**python (uv tool)**:\n\n```json\n{\n \"mcpServers\": {\n \"discord-py-self\": {\n \"command\": \"uv\",\n \"args\": [\"tool\", \"run\", \"discord-py-self-mcp\"],\n \"env\": {\n \"DISCORD_TOKEN\": \"${DISCORD_TOKEN}\"\n }\n }\n }\n}\n```\n\n**python (pip / venv)**:\n\n```json\n{\n \"mcpServers\": {\n \"discord-py-self\": {\n \"command\": \"python3\",\n \"args\": [\"-m\", \"discord_py_self_mcp.main\"],\n \"env\": {\n \"DISCORD_TOKEN\": \"${DISCORD_TOKEN}\"\n }\n }\n }\n}\n```\n\n> if your client does not expand `${DISCORD_TOKEN}`, replace it with the literal token value.\n\n### streamable HTTP transport\n\nThe default transport is stdio. For clients or local services that need a\npersistent endpoint, start the same MCP server with Streamable HTTP instead:\n\n```bash\npython3 -m discord_py_self_mcp.main --transport streamable-http --host 127.0.0.1 --port 7781\n```\n\nThis exposes the MCP endpoint at `http://127.0.0.1:7781/mcp`. The listener is\nlocalhost-only by default; place an authenticated reverse proxy or tunnel in\nfront of it if remote access is required. `MCP_TRANSPORT`, `MCP_HOST`, and\n`MCP_PORT` provide equivalent environment-based configuration.\n\n---\n\n### features\n\npowered by the robust `discord.py-self` library.\n\n| category | tools | description |\n|----------|-------|-------------|\n| **system** | 2 | get_user_info, list_guilds |\n| **messages** | 6 | send_message, read_messages, search_messages, edit_message, delete_message, get_message_attachments |\n| **channels** | 3 | create_channel, delete_channel, list_channels (bulk and compact summary modes) |\n| **dms** | 2 | list_dm_channels, list_unread_dms |\n| **pings** | 2 | list_pings, mark_message_read |\n| **voice** | 2 | join_voice_channel, leave_voice_channel |\n| **relationships** | 4 | list_friends, send_friend_request, add_friend, remove_friend |\n| **presence** | 2 | set_status, set_activity |\n| **interactions** | 8 | send_slash_command, click_button, select_menu, submit_modal, list_ephemeral_messages, list_application_commands, send_user_command, send_message_command |\n| **threads** | 5 | create_thread, send_thread_message, list_active_threads, read_thread_messages, archive_thread |\n| **members** | 5 | kick_member, ban_member, unban_member, add_role, remove_role |\n| **roles** | 6 | list_roles, get_role, create_role, edit_role, delete_role, reorder_roles |\n| **permissions** | 7 | set_role_permissions, get_channel_permissions, set_channel_permissions, patch_channel_permissions, remove_channel_permissions, set_category_permissions, inspect_effective_permissions |\n| **invites** | 3 | create_invite, list_invites, delete_invite |\n| **profile** | 1 | edit_profile |\n| **server folders** | 6 | list_server_folders, create_server_folder, move_server_to_folder, rename_server_folder, reorder_server_folders, apply_server_folder_layout |\n| **server discovery** | 3 | get_server_overviews, sample_server_content, analyze_server_sidebar |\n| **reactions** | 2 | add_reaction, remove_reaction |\n| **discrawl** | 7 | run_discrawl, discrawl_doctor, discrawl_status, discrawl_sync, discrawl_search, discrawl_messages, discrawl_mentions |\n\n### roles and permissions\n\n`list_roles` returns every role as JSON (id, name, color, position, permission\nbitfield) sorted highest-first. Run it before any restructuring — `position` is\nguild-wide, so moving one role reindexes the others and the dump is your only\nway back.\n\n`create_role` and `edit_role` take `color` as a hex string (`#5865F2`) or an\ninteger, and `permissions` as either a raw bitfield string or a list of flag\nnames (`[\"manage_roles\", \"kick_members\"]`). `edit_role` only touches the fields\nyou pass. `reorder_roles` moves several roles in one call and falls back to\nsequential edits when the bulk endpoint is unavailable.\n\nRole edits are bounded by hierarchy: your account cannot change a role at or\nabove your own highest role. Discord answers that with a bare 403, so these\ntools check position locally first and say which role is blocking. Guild owners\nare exempt.\n\n`set_channel_permissions` replaces an overwrite wholesale, so any flag you do\nnot pass is lost. When an overwrite already exists and you only mean to change\none flag, use `patch_channel_permissions` — it takes a map of flag to\ntrue/false/null and leaves everything else in that entry untouched. Because a\nwholesale write with neither `allow` nor `deny` would quietly wipe the entry,\nboth setters require at least one of the two and reject a flag listed in both;\n`remove_channel_permissions` is the way to drop an overwrite on purpose.\n\nRole moves are checked twice before anything is sent: the role must sit below\nyour own highest role, and so must the position you are moving it to. Both are\ncompared with discord's own role ordering rather than raw position numbers,\nsince positions can tie and are broken by id.\n\nFor channel access, `set_channel_permissions` writes one overwrite and\n`set_category_permissions` writes the category plus, by default, every channel\ninside it (`sync_children: false` to skip). `inspect_effective_permissions`\nresolves a role or member against every channel and reports what they can\nactually see — useful for checking a change landed the way you meant.\n\nFlag names are accepted in either spelling on input, but the `allowed` /\n`denied` lists in JSON output use discord.py-self's canonical names — so\n`view_channel` comes back as `read_messages`.\n\n### direct messages\n\n`list_dm_channels` enumerates your open 1:1 and group DM channels so you can\ndiscover a `channel_id` instead of needing to know it in advance. Each row is\n`