The bot token from DISCORD_BOT_TOKEN is used; this is not a user token.

How many members are fetched?

It fetches complete member lists using the HTTP API with pagination (1000 members per request), designed for large servers.

What if I encounter errors like Forbidden or Server not found?

Ensure SERVER MEMBERS INTENT is enabled and the bot has Read Members permission, verify the bot is added to the server, and confirm the token is correct.

discord-bot-members

npx machina-cli add skill lycfyi/community-agent-plugin/discord-bot-members --openclaw

Files (1)

SKILL.md

2.9 KB

Discord Bot Members

Syncs complete Discord server member lists using bot token via HTTP API. Optimized for large servers (100k+ members).

Works alongside discord.py-self - Uses direct HTTP API calls, no library conflicts.

When to Use

User asks to "sync members with bot token"
User needs "fast member sync" for large servers
User wants complete member lists (not just cached members)
User has a bot token and needs official API compliance

Prerequisites

Bot token in .env as DISCORD_BOT_TOKEN
Bot added to server with proper permissions
SERVER MEMBERS INTENT enabled in Discord Developer Portal
Python 3.11+ with aiohttp and pyyaml installed

Note: This plugin uses direct HTTP API calls via aiohttp. It works even when discord.py-self is installed (no namespace conflicts).

How to Execute

List servers the bot can access:

python {{PLUGIN_DIR}}/tools/member_sync.py --list

Sync members from a server:

python {{PLUGIN_DIR}}/tools/member_sync.py --server SERVER_ID

Include bot accounts:

python {{PLUGIN_DIR}}/tools/member_sync.py --server SERVER_ID --include-bots

Output Location

All paths are relative to cwd (current working directory). Uses unified path shared with user-connector:

data/discord/servers/{server_id}-{slug}/members/current.yaml
data/discord/servers/{server_id}-{slug}/members/snapshots/
data/discord/servers/{server_id}-{slug}/members/sync_history.yaml

Example Output

Connecting to Discord...
Syncing members from My Server (1234567890)...
Estimated members: 50,000

Syncing... [========================================] 50000/50000 (100.0%)

Sync complete in 75.4 seconds
- Total members: 50,000 (49,500 humans, 500 bots)

Data saved to: data/discord/servers/1234567890-my-server/members/

Troubleshooting

"Server not found" error:

Ensure the bot is added to the server
Check the server ID is correct

"Authentication failed" error:

Check your bot token in .env
Make sure it's a bot token, not a user token

"Forbidden" error:

Enable SERVER MEMBERS INTENT in Discord Developer Portal
Go to your application → Bot → Privileged Gateway Intents
Toggle "Server Members Intent" ON
Make sure bot has "Read Members" permission in the server

Only a few members returned:

This usually means SERVER MEMBERS INTENT is not enabled
Or the bot doesn't have permission to view members

Notes

Uses HTTP API pagination (1000 members per request)
Handles rate limiting automatically
Bot token provides official API compliance
No ToS concerns unlike user tokens
For rich profiles (bio, pronouns), use discord-user-connector plugin instead

Source

git clone https://github.com/lycfyi/community-agent-plugin/blob/main/plugins/discord-bot-connector/skills/discord-bot-members/SKILL.md

View on GitHub

Overview

Syncs complete Discord server member lists using a bot token via direct HTTP API. Optimized for large servers (100k+ members) and designed to avoid library conflicts by working alongside discord.py-self. It fetches the full member list, not just cached data.

How This Skill Works

The skill performs direct HTTP API calls using aiohttp to fetch server members, independent of discord.py-self. It paginates requests (1000 members per call) and handles rate limits, requiring a bot token and SERVER MEMBERS INTENT for official API access.

When to Use It

User asks to sync members with a bot token.
Need fast, scalable member sync for large servers (100k+).
User wants the full, up-to-date member list (not just cached).
Official API-compliant member fetch using a bot token.
Need to pull or verify server member lists across multiple servers.

Quick Start

Step 1: Set DISCORD_BOT_TOKEN in .env and ensure the bot is added to your server with correct permissions.
Step 2: Enable SERVER MEMBERS INTENT in the Discord Developer Portal and install required packages (aiohttp, pyyaml).
Step 3: Run a sync, e.g., python {{PLUGIN_DIR}}/tools/member_sync.py --server SERVER_ID [--include-bots].

Best Practices

Ensure SERVER MEMBERS INTENT is enabled in the Discord Developer Portal.
Store the bot token in .env as DISCORD_BOT_TOKEN.
Add the bot to the server with proper permissions.
Run on Python 3.11+ with aiohttp and pyyaml installed.
Be aware of HTTP API pagination and built-in rate limit handling; check outputs in data/discord/servers/

Example Use Cases

Sync all 50,000 members from My Server (1234567890) and save to data/discord/servers/1234567890-my-server/members/current.yaml.
Run with --include-bots to fetch bot accounts along with users.
List accessible servers with --list to verify reach before syncing.
Perform a nightly sync for a large server and review sync_history.yaml for changes.
If you see 'Forbidden', enable SERVER MEMBERS INTENT and verify Read Members permission for the bot.

Frequently Asked Questions

Add this skill to your agents