Personalizationmcp

🚀 PersonalizationMCP

A unified personal data hub built on MCP (Model Context Protocol). It enables AI assistants to access your digital life across multiple platforms, offering truly personalized and context-aware interactions.

📖 Chinese Documentation: README_zh.md

🚀 Quick Start

1. Clone the repository

   git clone https://github.com/YangLiangwei/PersonalizationMCP.git
   cd PersonalizationMCP
   

2. Install dependencies

   📖 See detailed installation instructions: Installation and Setup

3. Configure your API keys

   cp config.example config
   # Edit config file with your actual API keys
   

4. Add to Cursor settings

   📖 See detailed MCP configuration: Cursor Configuration

✨ Features

🎮 Steam Integration

• Retrieve your game library with comprehensive statistics and playtime data.
• View recent gaming activities and currently played games.
• Obtain detailed game information and achievements.
• Compare games with friends and receive personalized recommendations.
• Analyze your gaming habits and preferences.

🎥 YouTube Integration

• Search for YouTube videos and get in - depth video information.
• Access channel information and trending videos.
• Utilize OAuth2 to access personal data (subscriptions, playlists, liked videos).
• Receive personalized recommendations based on your viewing history.
• 🔄 Smart Token Management - Automatically detect and refresh expired OAuth2 tokens.
• 🛡️ Maintenance - Free Configuration - Prioritize token files, eliminating the need to manually update MCP configuration.

📺 Bilibili Integration

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

🎵 Spotify Integration

• Complete OAuth2 authentication with automatic token management.
• Fetch user profile and music library data.
• Access top artists, tracks, and recently played music.
• Enjoy social features such as following/unfollowing artists and playlists.
• Manage your music library, including saved tracks, albums, shows, episodes, and audiobooks.
• Perform playlist operations, such as viewing and managing personal playlists.

💬 Reddit Integration

• Complete OAuth2 authentication with automatic token management.
• Access user account information, karma breakdown, and preferences.
• Retrieve submitted posts, comments, and an overview of user activity.
• View saved content, hidden posts, and voting history.
• Explore subscribed communities and moderation permissions.
• Access the message system (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 Note: 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 | Chinese Guide

Quick summary: Obtain a 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 | Chinese Guide

Quick summary:

1. Get a YouTube API key from the Google Cloud Console.
2. For personal data access, set up OAuth2 with the "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 | Chinese Guide

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 | Chinese Guide

Quick summary:

1. Create a Spotify app in the 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 | Chinese Guide

Quick summary:

1. Create a Reddit app in Reddit Apps.
2. Configure it as a "web app" with a 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 a 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"
      }
    }
  }
}

⚠️ Important Note: For YouTube OAuth2 tokens,we recommend using automatic token management. There's 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: The system automatically detects tokens expiring within 5 minutes.
• Auto - Refresh: No manual intervention is required. The system automatically refreshes expired tokens.
• Smart Priority: Prioritizes token files, with environment variables as a backup.
• Maintenance - Free Configuration: Eliminates the 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, requiring no manual maintenance!

🛠️ Available Tools

🎮 Steam Tools

• get_steam_library() - Retrieve your game library with statistics.
• get_steam_recent_activity() - Get recent gaming activity.
• get_steam_friends() - Obtain your Steam friends list.
• get_steam_profile() - Fetch 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) - Obtain 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 the OAuth2 token.
• get_youtube_token_status() - Check the 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 in Total)

Authentication & Configuration (7 tools):

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

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 in Total)

Authentication & Configuration (6 tools):

• test_reddit_credentials() - Test API credentials.
• setup_reddit_oauth() - Initialize the OAuth flow.
• complete_reddit_oauth() - Complete OAuth authentication.
• get_reddit_token_status() - Get token status.
• refresh_reddit_token() - Manually refresh the token.
• auto_refresh_reddit_token_if_needed() - Automatic 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 a 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 the MCP server is working.
• get_personalization_status() - Get the 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."

🚀 Development

Running the Server

If using conda:

conda activate personalhub
python server.py

If using uv:

uv run python server.py

If using pip with a 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 platform - specific tools using the @mcp.tool() decorator.
3. Add the 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: Utilize 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: The Steam API has rate limits. Avoid frequent calls and implement reasonable delays.

Q: YouTube API quota exceeded? A: The 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 the configuration file format.
2. Verify that 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 into 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