Discord Relationship Visualizer

A toolkit designed to map your Discord social graph. This tool fetches your profile data (friends and guilds), identifies mutual connections, and renders a relationship visualizations.

Caution

TOS WARNING: This tool requires a Discord User Token. Using automated scripts on a user account violates Discord’s Terms of Service and can result in account suspension or a permanent ban. Proceed with caution and use this only for personal data exploration on accounts you own.

Ever wanted to see how your friend groups connected to each other? Now you can!

Friends and Servers Output	Friends Output

_{If you are in my example graph and would rather not be, let me know and I will remove you}

Quick Start

1. Environment Setup

Initialize your Python environment and install the necessary dependencies:

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Update core tools and install requirements
pip install --upgrade pip
pip install -r requirements.txt

2. Configuration (.env)

Copy the template file and input your credentials. Never share your token.

cp .env.example .env

Required Fields:

• MY_ID: Your user ID.
• DISCORD_TOKEN: Your personal authorization token. (Treat this like a password; do not share it with anyone.)
• CLIENT_ID & CLIENT_SECRET: Obtained from the Discord Developer Portal.

3. Discord OAuth Setup

To fetch server icons, you need a placeholder Discord application:

• Visit the Discord Developer Portal.
• Create a New Application.
• Navigate to the OAuth2 tab.
• Add a Redirect URI: http://localhost:8080/callback.
• Copy your Client ID and Client Secret into your .env file.

Execution

Run the scripts in the following order to build your graph:

Step	Script	Description
1	get_data.py	Fetches your profile and mutual friends. Saves to friends_data/<ID>.json
2	get_server_icons.py	Uses OAuth to retrieve server icon URLs and populates servers.json
3	ingest.py	Downloads and caches avatars/icons to icon_cache/ to prevent rate-limiting
4	visualize.py	Generates the final relationship graph in the output/ folder

Advanced configuration

You can adjust the fetch behavior and visual output directly in your .env file.

To remain "polite" to Discord’s API and avoid flags, the script uses these defaults:

• MIN_DELAY (seconds, default 1.5)
• MAX_DELAY (seconds, default 4.0)
• BATCH_SIZE (how many requests before a longer pause, default 30)
• BATCH_PAUSE (seconds to pause after a batch, default 60)
• REFRESH_DAYS (days before re-fetching an existing friend file, default 7)
• JSON_FOLDER / CACHE_DIR — where friend JSON and avatar cache live

These are to fine-tune the visualization output:

• CANVAS_SIZE, DPI — visualization canvas and resolution
• AVATAR_PIXELS, AVATAR_ZOOM — avatar processing and display

Data storage

• Sanitized profile files are saved to friends_data/<user_id>.json and contain only:
  • user.id, user.username, user.global_name, user.avatar
  • mutual_friends (list of {id, username, global_name, avatar})
  • mutual_guilds (list of {id, nick})

This minimizes sensitive data exposure.

Safety & Best Practices

• Do NOT share your .env or token publicly.
• Avoid running large fetch loops repeatedly; the script defaults to polite delays and batch pauses to reduce load.
• If you plan to publish or share visualizations, strip or anonymize identifying data.

Disclaimer

This software is provided "as is," for educational and personal research purposes only.

By using this toolkit, you acknowledge and agree to the following:

• Assumption of Risk: You understand that using a Discord user token to automate requests is a violation of Discord’s Terms of Service. You voluntarily assume all risks associated with this action, including but not limited to temporary or permanent account suspension (banning).
• No Liability: I will not be held responsible or liable for any consequences arising from the use of this software. This includes account termination, data loss, legal action, or any other damages—direct or indirect—resulting from the execution of these scripts.
• User Responsibility: You are solely responsible for the security of your credentials (token, client secret). I will never ask for your token, and you are advised never to share it with any third party.
• No Affiliation: This project is not affiliated with, endorsed by, or supported by Discord Inc.

If you do not agree to these terms, delete this repository and do not run the code.