🎯 PersonalizationMCP

A unified personal data hub built on MCP (Model Context Protocol) that allows AI assistants to access your digital life from multiple platforms, providing truly personalized and contextual interactions.

📖 中文文档: README_zh.md

🚀 Quick Start (Current Recommended Flow)

1. Clone and install

   bash

   Copy

   git clone https://github.com/YangLiangwei/PersonalizationMCP.git
   cd PersonalizationMCP
   
   # choose one
   uv venv && uv sync
   # or
   python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt
   

2. Run onboarding (interactive)

   bash

   Copy

   personalhub onboarding --all
   

3. Or run onboarding (non-interactive / scriptable)

   bash

   Copy

   personalhub onboarding --platform steam --set STEAM_API_KEY=xxx --set STEAM_USER_ID=7656119xxx
   personalhub onboarding --platform youtube --set YOUTUBE_API_KEY=xxx
   

4. Verify and run

   bash

   Copy

   personalhub status
   personalhub serve --profile safe
   

🧭 How the Project Works Now

• Unified entry for setup: personalhub onboarding
• Unified entry for operations: personalhub-manager skill
• Platform-specific flows: independent skills for Steam / YouTube / Bilibili / Spotify / Reddit
• No nested skill execution: one skill leads a task at a time

🌟 Features

🎮 Steam Integration

• Get your game library with detailed statistics and playtime
• View recent gaming activity and currently playing games
• Get detailed game information and achievements
• Compare games with friends and get recommendations
• Analyze gaming habits and preferences

🎥 YouTube Integration

• Search YouTube videos and get detailed video information
• Get channel information and trending videos
• Access personal data with OAuth2 (subscriptions, playlists, liked videos)
• Get personalized recommendations based on your viewing history
• 🔄 Smart Token Management - Automatically detect and refresh expired OAuth2 tokens
• 🛡️ Maintenance-Free Configuration - Prioritize token files, no need to manually update MCP configuration

📺 Bilibili Integration

• Get user profile information and statistics
• Search videos and get detailed video information
• Access personal data (watch history, favorites, liked videos, coin history)
• Get following list and user-uploaded videos
• Browse "to view later" list and personal collections

🎵 Spotify Integration

• Complete OAuth2 authentication with automatic token management
• Get user profile and music library data
• Access top artists, tracks, and recently played music
• Social features: follow/unfollow artists and playlists
• Library management: saved tracks, albums, shows, episodes, audiobooks
• Playlist operations: view and manage personal playlists

💬 Reddit Integration

• Complete OAuth2 authentication with automatic token management
• Access user account information, karma breakdown, and preferences
• Get submitted posts, comments, and user activity overview
• View saved content, hidden posts, and voting history
• Explore subscribed communities and moderation permissions
• Message system access (inbox, unread, sent messages)

📦 Installation and Setup

1. Install Dependencies

Due to the complexity of bilibili-api dependencies (especially lxml compilation issues), installation requires specific steps. Choose one of the methods below:

Option A: Using conda (Recommended)

# 1. Create conda environment
conda create -n personalhub python=3.12
conda activate personalhub

# 2. Install lxml via conda (avoids compilation issues)
conda install lxml

# 3. Install remaining packages
pip install bilibili-api --no-deps
pip install -r requirements.txt

Option B: Using uv

# 1. Install uv if not already installed
# Visit: https://docs.astral.sh/uv/getting-started/installation/

# 2. Create environment and install core dependencies
uv venv
uv sync
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Install bilibili-api and its dependencies separately (due to version conflicts)
uv pip install lxml  # Install lxml first (uses precompiled wheel)
uv pip install bilibili-api --no-deps  # Install bilibili-api without dependencies
uv pip install aiohttp beautifulsoup4 colorama PyYAML brotli urllib3  # Install required dependencies

Option C: Using pip (Manual Multi-Step Installation)

# 1. Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 2. Install packages in specific order to avoid compilation issues
pip install lxml  # Install lxml first (uses precompiled wheel)
pip install bilibili-api --no-deps  # Install bilibili-api without dependencies
pip install -r requirements.txt  # Install all other dependencies

⚠️ Important: The bilibili-api package has complex dependency requirements that can cause compilation failures on some systems. The multi-step installation approach ensures compatibility by installing lxml first, then bilibili-api without its conflicting dependencies, and finally all other required packages.

2. Configuration Setup

Copy the example configuration file and fill in your credentials:

cp config.example config

Then edit the config file with your actual API keys and tokens.

🔧 Platform Configuration

🎮 Steam API Setup

📖 Detailed setup guide: platforms/steam/README.md | 中文指南

Quick summary: Get Steam API key and User ID, then configure:

STEAM_API_KEY=your_steam_api_key_here
STEAM_USER_ID=your_steam_user_id_here

🎥 YouTube API Setup

📖 Detailed setup guide: platforms/youtube/README.md | 中文指南

Quick summary:

1. Get YouTube API key from Google Cloud Console
2. For personal data access, set up OAuth2 with "TV and Limited Input device" type
3. Use MCP tools for easy authentication

Configuration:

YOUTUBE_API_KEY=your_youtube_api_key_here
# OAuth2 tokens are managed automatically after setup

📺 Bilibili Setup

📖 Detailed setup guide: platforms/bilibili/README.md | 中文指南

Quick summary: Extract cookies from your browser after logging into Bilibili

Configuration:

BILIBILI_SESSDATA=your_bilibili_sessdata_cookie
BILIBILI_BILI_JCT=your_bilibili_bili_jct_cookie
BILIBILI_BUVID3=your_bilibili_buvid3_cookie

🎵 Spotify API Setup

📖 Detailed setup guide: platforms/spotify/README.md | 中文指南

Quick summary:

1. Create a Spotify app in Spotify Developer Dashboard
2. Configure redirect URIs in your app settings
3. Use MCP tools for OAuth2 authentication with automatic token management

Configuration:

SPOTIFY_CLIENT_ID=your_spotify_client_id_here
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret_here
SPOTIFY_REDIRECT_URI=https://example.com/callback
# OAuth2 tokens are managed automatically after authentication

💬 Reddit API Setup

📖 Detailed setup guide: platforms/reddit/README.md | 中文指南

Quick summary:

1. Create a Reddit app in Reddit Apps
2. Configure as "web app" with redirect URI
3. Use MCP tools for OAuth2 authentication with automatic token management

Configuration:

REDDIT_CLIENT_ID=your_reddit_client_id_here
REDDIT_CLIENT_SECRET=your_reddit_client_secret_here
REDDIT_REDIRECT_URI=http://localhost:8888/callback
# OAuth2 tokens are managed automatically after authentication

🖥️ Cursor Configuration

Add the MCP server to your Cursor settings:

If using conda:

{
  "mcpServers": {
    "personalhub": {
      "command": "/path/to/your/conda/envs/personalhub/bin/python",
      "args": ["/absolute/path/to/your/project/server.py"],
      "env": {
        "STEAM_API_KEY": "your_steam_api_key",
        "STEAM_USER_ID": "your_steam_user_id",
        "YOUTUBE_API_KEY": "your_youtube_api_key",
        "BILIBILI_SESSDATA": "your_bilibili_sessdata",
        "BILIBILI_BILI_JCT": "your_bilibili_bili_jct",
        "BILIBILI_BUVID3": "your_bilibili_buvid3",
        "REDDIT_CLIENT_ID": "your_reddit_client_id",
        "REDDIT_CLIENT_SECRET": "your_reddit_client_secret"
      }
    }
  }
}

If using uv:

{
  "mcpServers": {
    "personalhub": {
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/your/project/server.py"],
      "env": {
        "STEAM_API_KEY": "your_steam_api_key",
        "STEAM_USER_ID": "your_steam_user_id",
        "YOUTUBE_API_KEY": "your_youtube_api_key",
        "BILIBILI_SESSDATA": "your_bilibili_sessdata",
        "BILIBILI_BILI_JCT": "your_bilibili_bili_jct",
        "BILIBILI_BUVID3": "your_bilibili_buvid3",
        "REDDIT_CLIENT_ID": "your_reddit_client_id",
        "REDDIT_CLIENT_SECRET": "your_reddit_client_secret"
      }
    }
  }
}

If using pip with virtual environment:

{
  "mcpServers": {
    "personalhub": {
      "command": "/absolute/path/to/your/project/venv/bin/python",
      "args": ["/absolute/path/to/your/project/server.py"],
      "env": {
        "STEAM_API_KEY": "your_steam_api_key",
        "STEAM_USER_ID": "your_steam_user_id",
        "YOUTUBE_API_KEY": "your_youtube_api_key",
        "BILIBILI_SESSDATA": "your_bilibili_sessdata",
        "BILIBILI_BILI_JCT": "your_bilibili_bili_jct",
        "BILIBILI_BUVID3": "your_bilibili_buvid3",
        "REDDIT_CLIENT_ID": "your_reddit_client_id",
        "REDDIT_CLIENT_SECRET": "your_reddit_client_secret"
      }
    }
  }
}

Note: For YouTube OAuth2 tokens, we recommend using automatic token management. No need to add YOUTUBE_ACCESS_TOKEN in the above configuration. The system will automatically read and refresh tokens from the youtube_tokens.json file.

🔄 YouTube Smart Token Management

This system implements intelligent YouTube OAuth2 token management with the following features:

✨ Core Features

• Automatic Expiration Detection: System automatically detects tokens expiring within 5 minutes
• Auto-Refresh: No manual intervention needed, system automatically refreshes expired tokens
• Smart Priority: Prioritizes token files, with environment variables as backup
• Maintenance-Free Configuration: No need to manually update tokens in MCP configuration files

🔧 Token Priority

1. Explicitly passed access_token parameter (Highest priority)
2. Auto-refresh tokens from token file (Recommended method)
3. Tokens from environment variables (Backup method)

The system automatically handles all token management - no manual maintenance required!

🛠️ Available Tools

🎮 Steam Tools

• get_steam_library() - Get your game library with statistics
• get_steam_recent_activity() - Get recent gaming activity
• get_steam_friends() - Get your Steam friends list
• get_steam_profile() - Get Steam profile information
• get_player_achievements(app_id) - Get achievements for a specific game
• get_user_game_stats(app_id) - Get detailed game statistics
• get_friends_current_games() - See what games your friends are playing
• compare_games_with_friend(friend_steamid) - Compare game libraries
• get_friend_game_recommendations(friend_steamid) - Get game recommendations

🎥 YouTube Tools

• search_youtube_videos(query) - Search for videos
• get_video_details(video_id) - Get detailed video information
• get_channel_info(channel_id) - Get channel information
• get_trending_videos() - Get trending videos
• get_youtube_subscriptions() - Get your subscriptions (OAuth2 required)
• get_youtube_playlists() - Get your playlists (OAuth2 required)
• get_youtube_liked_videos() - Get your liked videos (OAuth2 required)
• refresh_youtube_token() - Manually refresh OAuth2 token
• get_youtube_token_status() - Check OAuth2 token status

📺 Bilibili Tools

• get_bilibili_user_info(uid) - Get user profile information
• get_my_bilibili_profile() - Get your own profile
• search_bilibili_videos(keyword) - Search for videos
• get_bilibili_video_info(bvid) - Get detailed video information
• get_bilibili_user_videos(uid) - Get videos uploaded by a user
• get_bilibili_following_list() - Get your following list
• get_bilibili_watch_history() - Get your watch history
• get_bilibili_favorites() - Get your favorite videos
• get_bilibili_liked_videos() - Get your liked videos
• get_bilibili_coin_videos() - Get videos you've given coins to
• get_bilibili_toview_list() - Get your "to view later" list

🎵 Spotify Tools (17 Total)

Authentication & Configuration (7 tools):

• test_spotify_credentials() - Test API credentials
• setup_spotify_oauth() - Initialize OAuth flow
• complete_spotify_oauth() - Complete OAuth authentication
• get_spotify_token_status() - Get token status
• refresh_spotify_token() - Manual token refresh

Music Discovery & Social (9 tools):

• get_current_user_profile() - Get your Spotify profile
• get_user_top_items() - Get top artists/tracks
• get_user_recently_played() - Get recently played music
• get_followed_artists() - Get followed artists
• follow_artists_or_users() / unfollow_artists_or_users() - Social features

Library & Playlists (6 tools):

• get_user_saved_tracks() / get_user_saved_albums() - Library management
• get_user_saved_shows() / get_user_saved_episodes() - Podcast content
• get_current_user_playlists() / get_playlist_items() - Playlist operations

💬 Reddit Tools (25 Total)

Authentication & Configuration (6 tools):

• test_reddit_credentials() - Test API credentials
• setup_reddit_oauth() - Initialize OAuth flow
• complete_reddit_oauth() - Complete OAuth authentication
• get_reddit_token_status() - Get token status
• refresh_reddit_token() - Manual token refresh
• auto_refresh_reddit_token_if_needed() - Auto token management

Account Information (6 tools):

• get_user_subreddits() - Get subscribed communities
• get_user_trophies() - Get Reddit trophies and achievements
• get_user_preferences() - Get account settings
• get_user_karma_breakdown() - Get karma distribution
• get_moderated_subreddits() - Get moderated communities
• get_contributor_subreddits() - Get contributor permissions

Content & Activity (10 tools):

• get_user_submitted_posts() - Get submitted posts
• get_user_comments() - Get comment history
• get_user_overview() - Get mixed activity timeline
• get_saved_content() - Get saved posts/comments
• get_hidden_posts() - Get hidden content
• get_upvoted_content() - Get upvoted content
• get_downvoted_content() - Get downvoted content

Messaging (3 tools):

• get_inbox_messages() - Get inbox messages
• get_unread_messages() - Get unread messages
• get_sent_messages() - Get sent messages

🔧 System Tools

• test_connection() - Test if MCP server is working
• get_personalization_status() - Get overall platform status
• test_steam_credentials() - Test Steam API configuration
• test_youtube_credentials() - Test YouTube API configuration
• test_bilibili_credentials() - Test Bilibili configuration
• test_spotify_credentials() - Test Spotify API configuration
• test_reddit_credentials() - Test Reddit API configuration

💬 Usage Examples

Gaming Analysis

• "What games have I been playing recently?"
• "Show me my most played Steam games"
• "What games do my friends recommend?"
• "Compare my game library with my friend's"

Video Content Discovery

• "Find YouTube videos about machine learning"
• "What are the trending videos on YouTube today?"
• "Show me my YouTube liked videos"
• "Find popular Bilibili videos about programming"

Personal Data Insights

• "Analyze my gaming habits and preferences"
• "What type of YouTube content do I watch most?"
• "Show me my Bilibili favorites and liked videos"

Music & Audio Analysis

• "What artists have I been listening to most lately on Spotify?"
• "Show me my recently played music and find patterns"
• "What are my top tracks from the past month?"
• "Find new music recommendations based on my Spotify data"

Reddit Activity Analysis

• "What communities am I most active in on Reddit?"
• "Show me my recent Reddit posts and comments"
• "What's my karma breakdown across different subreddits?"
• "Find my saved Reddit content and analyze my interests"

🧩 Skills (CLI-oriented)

This repo now includes standalone skills under skills/ that map directly to personalhub CLI workflows:

• personalhub-onboarding (unified credential onboarding entry)
• personalhub-manager (aggregate day-2 manager)
• personalhub-status
• personalhub-steam
• personalhub-youtube
• personalhub-bilibili
• personalhub-spotify
• personalhub-reddit

Pattern: one unified entry + platform-specific skills. Each skill remains independent (no nested execution).

🚀 Development

Running the Server

Recommended (CLI with tool exposure profiles):

# Safer default: expose a curated subset of tools
personalhub serve --profile safe

# Legacy behavior: expose all tools
personalhub serve --profile full

# See available profiles
personalhub profiles

# Show integration status
personalhub status

# Interactive onboarding (recommended for first-time setup)
personalhub onboarding --platform steam,youtube
personalhub onboarding --all
personalhub onboarding --platform steam --set STEAM_API_KEY=xxx --set STEAM_USER_ID=7656119xxx

# Run direct Steam commands (without MCP)
personalhub steam credentials
personalhub steam library
personalhub steam profile

# Run direct YouTube commands (without MCP)
personalhub youtube credentials
personalhub youtube search -q "lofi"
personalhub youtube trending --region-code US

# Run direct Spotify commands
personalhub spotify credentials
personalhub spotify token-status
personalhub spotify recent --limit 20

# Run direct Reddit commands
personalhub reddit credentials
personalhub reddit token-status
personalhub reddit subreddits --limit 20

# Run direct Bilibili commands
personalhub bilibili credentials
personalhub bilibili search -k "编程"
personalhub bilibili video --bvid BV1xx411c7mD

If using conda:

conda activate personalhub
python server.py

If using uv:

uv run python server.py

If using pip with virtual environment:

source venv/bin/activate  # On Windows: venv\Scripts\activate
python server.py

Testing Configuration

Use these tools to test your setup:

# Test individual platforms
test_steam_credentials()
test_youtube_credentials()
test_bilibili_credentials()
test_reddit_credentials()

# Check overall status
get_personalization_status()

Adding New Platforms

1. Create a new platform_mcp.py file
2. Implement the platform-specific tools using @mcp.tool() decorator
3. Add setup function to server.py
4. Update configuration files and documentation

🔒 Privacy and Security

• Local Storage: All API keys and tokens are stored locally on your machine
• No Data Transmission: Your personal data is never transmitted to third parties
• Direct API Calls: All API calls are made directly from your machine to the respective platforms
• Secure Configuration: Use environment variables or local config files
• Regular Updates: Rotate API keys and tokens regularly for security

Security Best Practices

1. Don't commit sensitive files: Ensure config, .env, myinfo.json, and youtube_tokens.json are in .gitignore
2. Update cookies regularly: Bilibili cookies expire and need periodic updates
3. Use environment variables: In production, use system environment variables
4. File permissions: Ensure config files are only readable by you
5. YouTube token security: The system automatically manages OAuth2 tokens securely in local files
6. Gradual configuration: You can configure platforms incrementally - missing credentials won't cause errors

🆘 Troubleshooting

Common Issues

Q: Bilibili cookies not working? A: Cookies expire regularly. Re-extract them from your browser and update your config.

Q: Steam API rate limits? A: Steam API has rate limits. Avoid frequent calls and implement reasonable delays.

Q: YouTube API quota exceeded? A: YouTube API has daily quotas. You can request quota increases or optimize your usage.

Q: YouTube OAuth2 token expired? A: The system automatically refreshes expired tokens. If manual refresh is needed, use refresh_youtube_token().

Q: Can I use only some platforms? A: Yes! You can configure only the platforms you want to use. Missing credentials won't cause errors.

Q: How to verify my configuration? A: Use the test tools or call get_personalization_status() to check all platforms.

Getting Help

1. Check configuration file format
2. Verify API keys and cookies are valid
3. Review MCP server logs
4. Use test tools to validate each platform configuration

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests if applicable
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

Adding New Platforms

Want to add support for a new platform? Follow these steps:

1. Create a new platform_mcp.py file (e.g., spotify_mcp.py)
2. Implement platform-specific tools using the @mcp.tool() decorator
3. Add a setup function and integrate it in server.py
4. Update configuration files and documentation
5. Add tests and examples

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol (MCP) for the amazing protocol
• Anthropic for Claude and MCP development
• All the platform APIs that make this integration possible

⭐ Star History

If you find this project useful, please consider giving it a star on GitHub!

Made with ❤️ for connecting your digital life with AI