PersonalizationMCP

1# 🎯 PersonalizationMCP
2 
3[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
5[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
6 
7A 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.
8 
9> 📖 **中文文档**: [README_zh.md](README_zh.md)
10 
11## 🚀 Quick Start
12 
131. **Clone the repository**
14   ```bash
15   git clone https://github.com/YangLiangwei/PersonalizationMCP.git
16   cd PersonalizationMCP
17   ```
18 
192. **Install dependencies**
20   
21   > 📖 **See detailed installation instructions: [Installation and Setup](#-installation-and-setup)**
22 
233. **Configure your API keys**
24   ```bash
25   cp config.example config
26   # Edit config file with your actual API keys
27   ```
28 
294. **Add to Cursor settings**
30   
31   > 📖 **See detailed MCP configuration: [Cursor Configuration](#-cursor-configuration)**
32 
33## 🌟 Features
34 
35### 🎮 Steam Integration
36- Get your game library with detailed statistics and playtime
37- View recent gaming activity and currently playing games
38- Get detailed game information and achievements
39- Compare games with friends and get recommendations
40- Analyze gaming habits and preferences
41 
42### 🎥 YouTube Integration
43- Search YouTube videos and get detailed video information
44- Get channel information and trending videos
45- Access personal data with OAuth2 (subscriptions, playlists, liked videos)
46- Get personalized recommendations based on your viewing history
47- 🔄 **Smart Token Management** - Automatically detect and refresh expired OAuth2 tokens
48- 🛡️ **Maintenance-Free Configuration** - Prioritize token files, no need to manually update MCP configuration
49 
50### 📺 Bilibili Integration
51- Get user profile information and statistics
52- Search videos and get detailed video information
53- Access personal data (watch history, favorites, liked videos, coin history)
54- Get following list and user-uploaded videos
55- Browse "to view later" list and personal collections
56 
57### 🎵 Spotify Integration
58- Complete OAuth2 authentication with automatic token management
59- Get user profile and music library data
60- Access top artists, tracks, and recently played music
61- Social features: follow/unfollow artists and playlists
62- Library management: saved tracks, albums, shows, episodes, audiobooks
63- Playlist operations: view and manage personal playlists
64 
65### 💬 Reddit Integration
66- Complete OAuth2 authentication with automatic token management
67- Access user account information, karma breakdown, and preferences
68- Get submitted posts, comments, and user activity overview
69- View saved content, hidden posts, and voting history
70- Explore subscribed communities and moderation permissions
71- Message system access (inbox, unread, sent messages)
72 
73## 📦 Installation and Setup
74 
75### 1. Install Dependencies
76 
77Due to the complexity of bilibili-api dependencies (especially lxml compilation issues), installation requires specific steps. Choose one of the methods below:
78 
79#### **Option A: Using conda (Recommended)**
80```bash
81# 1. Create conda environment
82conda create -n personalhub python=3.12
83conda activate personalhub
84 
85# 2. Install lxml via conda (avoids compilation issues)
86conda install lxml
87 
88# 3. Install remaining packages
89pip install bilibili-api --no-deps
90pip install -r requirements.txt
91```
92 
93#### **Option B: Using uv**
94```bash
95# 1. Install uv if not already installed
96# Visit: https://docs.astral.sh/uv/getting-started/installation/
97 
98# 2. Create environment and install core dependencies
99uv venv
100uv sync
101source .venv/bin/activate  # On Windows: .venv\Scripts\activate
102 
103# 3. Install bilibili-api and its dependencies separately (due to version conflicts)
104uv pip install lxml  # Install lxml first (uses precompiled wheel)
105uv pip install bilibili-api --no-deps  # Install bilibili-api without dependencies
106uv pip install aiohttp beautifulsoup4 colorama PyYAML brotli urllib3  # Install required dependencies
107```
108 
109#### **Option C: Using pip (Manual Multi-Step Installation)**
110```bash
111# 1. Create virtual environment
112python -m venv venv
113source venv/bin/activate  # On Windows: venv\Scripts\activate
114 
115# 2. Install packages in specific order to avoid compilation issues
116pip install lxml  # Install lxml first (uses precompiled wheel)
117pip install bilibili-api --no-deps  # Install bilibili-api without dependencies
118pip install -r requirements.txt  # Install all other dependencies
119```
120 
121> **⚠️ 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.
122 
123### 2. Configuration Setup
124 
125Copy the example configuration file and fill in your credentials:
126```bash
127cp config.example config
128```
129 
130Then edit the `config` file with your actual API keys and tokens.
131 
132## 🔧 Platform Configuration
133 
134### 🎮 Steam API Setup
135 
136> 📖 **Detailed setup guide**: [platforms/steam/README.md](platforms/steam/README.md) | [中文指南](platforms/steam/README_zh.md)
137 
138**Quick summary**: Get Steam API key and User ID, then configure:
139```bash
140STEAM_API_KEY=your_steam_api_key_here
141STEAM_USER_ID=your_steam_user_id_here
142```
143 
144### 🎥 YouTube API Setup
145 
146> 📖 **Detailed setup guide**: [platforms/youtube/README.md](platforms/youtube/README.md) | [中文指南](platforms/youtube/README_zh.md)
147 
148**Quick summary**: 
1491. Get YouTube API key from Google Cloud Console
1502. For personal data access, set up OAuth2 with "TV and Limited Input device" type
1513. Use MCP tools for easy authentication
152 
153**Configuration:**
154```bash
155YOUTUBE_API_KEY=your_youtube_api_key_here
156# OAuth2 tokens are managed automatically after setup
157```
158 
159### 📺 Bilibili Setup
160 
161> 📖 **Detailed setup guide**: [platforms/bilibili/README.md](platforms/bilibili/README.md) | [中文指南](platforms/bilibili/README_zh.md)
162 
163**Quick summary**: Extract cookies from your browser after logging into Bilibili
164 
165**Configuration:**
166```bash
167BILIBILI_SESSDATA=your_bilibili_sessdata_cookie
168BILIBILI_BILI_JCT=your_bilibili_bili_jct_cookie
169BILIBILI_BUVID3=your_bilibili_buvid3_cookie
170```
171 
172### 🎵 Spotify API Setup
173 
174> 📖 **Detailed setup guide**: [platforms/spotify/README.md](platforms/spotify/README.md) | [中文指南](platforms/spotify/README_zh.md)
175 
176**Quick summary**: 
1771. Create a Spotify app in [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
1782. Configure redirect URIs in your app settings
1793. Use MCP tools for OAuth2 authentication with automatic token management
180 
181**Configuration:**
182```bash
183SPOTIFY_CLIENT_ID=your_spotify_client_id_here
184SPOTIFY_CLIENT_SECRET=your_spotify_client_secret_here
185SPOTIFY_REDIRECT_URI=https://example.com/callback
186# OAuth2 tokens are managed automatically after authentication
187```
188 
189### 💬 Reddit API Setup
190 
191> 📖 **Detailed setup guide**: [platforms/reddit/README.md](platforms/reddit/README.md) | [中文指南](platforms/reddit/README_zh.md)
192 
193**Quick summary**: 
1941. Create a Reddit app in [Reddit Apps](https://www.reddit.com/prefs/apps)
1952. Configure as "web app" with redirect URI
1963. Use MCP tools for OAuth2 authentication with automatic token management
197 
198**Configuration:**
199```bash
200REDDIT_CLIENT_ID=your_reddit_client_id_here
201REDDIT_CLIENT_SECRET=your_reddit_client_secret_here
202REDDIT_REDIRECT_URI=http://localhost:8888/callback
203# OAuth2 tokens are managed automatically after authentication
204```
205 
206## 🖥️ Cursor Configuration
207 
208Add the MCP server to your Cursor settings:
209 
210**If using conda:**
211```json
212{
213  "mcpServers": {
214    "personalhub": {
215      "command": "/path/to/your/conda/envs/personalhub/bin/python",
216      "args": ["/absolute/path/to/your/project/server.py"],
217      "env": {
218        "STEAM_API_KEY": "your_steam_api_key",
219        "STEAM_USER_ID": "your_steam_user_id",
220        "YOUTUBE_API_KEY": "your_youtube_api_key",
221        "BILIBILI_SESSDATA": "your_bilibili_sessdata",
222        "BILIBILI_BILI_JCT": "your_bilibili_bili_jct",
223        "BILIBILI_BUVID3": "your_bilibili_buvid3",
224        "REDDIT_CLIENT_ID": "your_reddit_client_id",
225        "REDDIT_CLIENT_SECRET": "your_reddit_client_secret"
226      }
227    }
228  }
229}
230```
231 
232**If using uv:**
233```json
234{
235  "mcpServers": {
236    "personalhub": {
237      "command": "uv",
238      "args": ["run", "python", "/absolute/path/to/your/project/server.py"],
239      "env": {
240        "STEAM_API_KEY": "your_steam_api_key",
241        "STEAM_USER_ID": "your_steam_user_id",
242        "YOUTUBE_API_KEY": "your_youtube_api_key",
243        "BILIBILI_SESSDATA": "your_bilibili_sessdata",
244        "BILIBILI_BILI_JCT": "your_bilibili_bili_jct",
245        "BILIBILI_BUVID3": "your_bilibili_buvid3",
246        "REDDIT_CLIENT_ID": "your_reddit_client_id",
247        "REDDIT_CLIENT_SECRET": "your_reddit_client_secret"
248      }
249    }
250  }
251}
252```
253 
254**If using pip with virtual environment:**
255```json
256{
257  "mcpServers": {
258    "personalhub": {
259      "command": "/absolute/path/to/your/project/venv/bin/python",
260      "args": ["/absolute/path/to/your/project/server.py"],
261      "env": {
262        "STEAM_API_KEY": "your_steam_api_key",
263        "STEAM_USER_ID": "your_steam_user_id",
264        "YOUTUBE_API_KEY": "your_youtube_api_key",
265        "BILIBILI_SESSDATA": "your_bilibili_sessdata",
266        "BILIBILI_BILI_JCT": "your_bilibili_bili_jct",
267        "BILIBILI_BUVID3": "your_bilibili_buvid3",
268        "REDDIT_CLIENT_ID": "your_reddit_client_id",
269        "REDDIT_CLIENT_SECRET": "your_reddit_client_secret"
270      }
271    }
272  }
273}
274```
275 
276**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.
277 
278## 🔄 YouTube Smart Token Management
279 
280This system implements intelligent YouTube OAuth2 token management with the following features:
281 
282### ✨ Core Features
283- **Automatic Expiration Detection**: System automatically detects tokens expiring within 5 minutes
284- **Auto-Refresh**: No manual intervention needed, system automatically refreshes expired tokens
285- **Smart Priority**: Prioritizes token files, with environment variables as backup
286- **Maintenance-Free Configuration**: No need to manually update tokens in MCP configuration files
287 
288### 🔧 Token Priority
2891. **Explicitly passed access_token parameter** (Highest priority)
2902. **Auto-refresh tokens from token file** (Recommended method)
2913. **Tokens from environment variables** (Backup method)
292 
293 
294The system automatically handles all token management - no manual maintenance required!
295 
296## 🛠️ Available Tools
297 
298### 🎮 Steam Tools
299- `get_steam_library()` - Get your game library with statistics
300- `get_steam_recent_activity()` - Get recent gaming activity
301- `get_steam_friends()` - Get your Steam friends list
302- `get_steam_profile()` - Get Steam profile information
303- `get_player_achievements(app_id)` - Get achievements for a specific game
304- `get_user_game_stats(app_id)` - Get detailed game statistics
305- `get_friends_current_games()` - See what games your friends are playing
306- `compare_games_with_friend(friend_steamid)` - Compare game libraries
307- `get_friend_game_recommendations(friend_steamid)` - Get game recommendations
308 
309### 🎥 YouTube Tools
310- `search_youtube_videos(query)` - Search for videos
311- `get_video_details(video_id)` - Get detailed video information
312- `get_channel_info(channel_id)` - Get channel information
313- `get_trending_videos()` - Get trending videos
314- `get_youtube_subscriptions()` - Get your subscriptions (OAuth2 required)
315- `get_youtube_playlists()` - Get your playlists (OAuth2 required)
316- `get_youtube_liked_videos()` - Get your liked videos (OAuth2 required)
317- `refresh_youtube_token()` - Manually refresh OAuth2 token
318- `get_youtube_token_status()` - Check OAuth2 token status
319 
320### 📺 Bilibili Tools
321- `get_bilibili_user_info(uid)` - Get user profile information
322- `get_my_bilibili_profile()` - Get your own profile
323- `search_bilibili_videos(keyword)` - Search for videos
324- `get_bilibili_video_info(bvid)` - Get detailed video information
325- `get_bilibili_user_videos(uid)` - Get videos uploaded by a user
326- `get_bilibili_following_list()` - Get your following list
327- `get_bilibili_watch_history()` - Get your watch history
328- `get_bilibili_favorites()` - Get your favorite videos
329- `get_bilibili_liked_videos()` - Get your liked videos
330- `get_bilibili_coin_videos()` - Get videos you've given coins to
331- `get_bilibili_toview_list()` - Get your "to view later" list
332 
333### 🎵 Spotify Tools (17 Total)
334 
335**Authentication & Configuration (7 tools):**
336- `test_spotify_credentials()` - Test API credentials
337- `setup_spotify_oauth()` - Initialize OAuth flow
338- `complete_spotify_oauth()` - Complete OAuth authentication
339- `get_spotify_token_status()` - Get token status
340- `refresh_spotify_token()` - Manual token refresh
341 
342**Music Discovery & Social (9 tools):**
343- `get_current_user_profile()` - Get your Spotify profile
344- `get_user_top_items()` - Get top artists/tracks
345- `get_user_recently_played()` - Get recently played music
346- `get_followed_artists()` - Get followed artists
347- `follow_artists_or_users()` / `unfollow_artists_or_users()` - Social features
348 
349**Library & Playlists (6 tools):**
350- `get_user_saved_tracks()` / `get_user_saved_albums()` - Library management
351- `get_user_saved_shows()` / `get_user_saved_episodes()` - Podcast content
352- `get_current_user_playlists()` / `get_playlist_items()` - Playlist operations
353 
354### 💬 Reddit Tools (25 Total)
355 
356**Authentication & Configuration (6 tools):**
357- `test_reddit_credentials()` - Test API credentials
358- `setup_reddit_oauth()` - Initialize OAuth flow
359- `complete_reddit_oauth()` - Complete OAuth authentication
360- `get_reddit_token_status()` - Get token status
361- `refresh_reddit_token()` - Manual token refresh
362- `auto_refresh_reddit_token_if_needed()` - Auto token management
363 
364**Account Information (6 tools):**
365- `get_user_subreddits()` - Get subscribed communities
366- `get_user_trophies()` - Get Reddit trophies and achievements
367- `get_user_preferences()` - Get account settings
368- `get_user_karma_breakdown()` - Get karma distribution
369- `get_moderated_subreddits()` - Get moderated communities
370- `get_contributor_subreddits()` - Get contributor permissions
371 
372**Content & Activity (10 tools):**
373- `get_user_submitted_posts()` - Get submitted posts
374- `get_user_comments()` - Get comment history
375- `get_user_overview()` - Get mixed activity timeline
376- `get_saved_content()` - Get saved posts/comments
377- `get_hidden_posts()` - Get hidden content
378- `get_upvoted_content()` - Get upvoted content
379- `get_downvoted_content()` - Get downvoted content
380 
381**Messaging (3 tools):**
382- `get_inbox_messages()` - Get inbox messages
383- `get_unread_messages()` - Get unread messages
384- `get_sent_messages()` - Get sent messages
385 
386### 🔧 System Tools
387- `test_connection()` - Test if MCP server is working
388- `get_personalization_status()` - Get overall platform status
389- `test_steam_credentials()` - Test Steam API configuration
390- `test_youtube_credentials()` - Test YouTube API configuration
391- `test_bilibili_credentials()` - Test Bilibili configuration
392- `test_spotify_credentials()` - Test Spotify API configuration
393- `test_reddit_credentials()` - Test Reddit API configuration
394 
395## 💬 Usage Examples
396 
397### Gaming Analysis
398- "What games have I been playing recently?"
399- "Show me my most played Steam games"
400- "What games do my friends recommend?"
401- "Compare my game library with my friend's"
402 
403### Video Content Discovery
404- "Find YouTube videos about machine learning"
405- "What are the trending videos on YouTube today?"
406- "Show me my YouTube liked videos"
407- "Find popular Bilibili videos about programming"
408 
409### Personal Data Insights
410- "Analyze my gaming habits and preferences"
411- "What type of YouTube content do I watch most?"
412- "Show me my Bilibili favorites and liked videos"
413 
414### Music & Audio Analysis
415- "What artists have I been listening to most lately on Spotify?"
416- "Show me my recently played music and find patterns"
417- "What are my top tracks from the past month?"
418- "Find new music recommendations based on my Spotify data"
419 
420### Reddit Activity Analysis
421- "What communities am I most active in on Reddit?"
422- "Show me my recent Reddit posts and comments"
423- "What's my karma breakdown across different subreddits?"
424- "Find my saved Reddit content and analyze my interests"
425 
426## 🚀 Development
427 
428### Running the Server
429 
430**If using conda:**
431```bash
432conda activate personalhub
433python server.py
434```
435 
436**If using uv:**
437```bash
438uv run python server.py
439```
440 
441**If using pip with virtual environment:**
442```bash
443source venv/bin/activate  # On Windows: venv\Scripts\activate
444python server.py
445```
446 
447### Testing Configuration
448Use these tools to test your setup:
449```python
450# Test individual platforms
451test_steam_credentials()
452test_youtube_credentials()
453test_bilibili_credentials()
454test_reddit_credentials()
455 
456# Check overall status
457get_personalization_status()
458```
459 
460### Adding New Platforms
4611. Create a new `platform_mcp.py` file
4622. Implement the platform-specific tools using `@mcp.tool()` decorator
4633. Add setup function to `server.py`
4644. Update configuration files and documentation
465 
466## 🔒 Privacy and Security
467 
468- **Local Storage**: All API keys and tokens are stored locally on your machine
469- **No Data Transmission**: Your personal data is never transmitted to third parties
470- **Direct API Calls**: All API calls are made directly from your machine to the respective platforms
471- **Secure Configuration**: Use environment variables or local config files
472- **Regular Updates**: Rotate API keys and tokens regularly for security
473 
474### Security Best Practices
4751. **Don't commit sensitive files**: Ensure `config`, `.env`, `myinfo.json`, and `youtube_tokens.json` are in `.gitignore`
4762. **Update cookies regularly**: Bilibili cookies expire and need periodic updates
4773. **Use environment variables**: In production, use system environment variables
4784. **File permissions**: Ensure config files are only readable by you
4795. **YouTube token security**: The system automatically manages OAuth2 tokens securely in local files
4806. **Gradual configuration**: You can configure platforms incrementally - missing credentials won't cause errors
481 
482## 🆘 Troubleshooting
483 
484### Common Issues
485 
486**Q: Bilibili cookies not working?**
487A: Cookies expire regularly. Re-extract them from your browser and update your config.
488 
489**Q: Steam API rate limits?**
490A: Steam API has rate limits. Avoid frequent calls and implement reasonable delays.
491 
492**Q: YouTube API quota exceeded?**
493A: YouTube API has daily quotas. You can request quota increases or optimize your usage.
494 
495**Q: YouTube OAuth2 token expired?**
496A: The system automatically refreshes expired tokens. If manual refresh is needed, use `refresh_youtube_token()`.
497 
498**Q: Can I use only some platforms?**
499A: Yes! You can configure only the platforms you want to use. Missing credentials won't cause errors.
500 
501**Q: How to verify my configuration?**
502A: Use the test tools or call `get_personalization_status()` to check all platforms.
503 
504### Getting Help
5051. Check configuration file format
5062. Verify API keys and cookies are valid
5073. Review MCP server logs
5084. Use test tools to validate each platform configuration
509 
510## 🤝 Contributing
511 
512Contributions are welcome! Here's how you can help:
513 
5141. **Fork the repository**
5152. **Create a feature branch**: `git checkout -b feature/amazing-feature`
5163. **Make your changes** and add tests if applicable
5174. **Commit your changes**: `git commit -m 'Add amazing feature'`
5185. **Push to the branch**: `git push origin feature/amazing-feature`
5196. **Open a Pull Request**
520 
521### Adding New Platforms
522 
523Want to add support for a new platform? Follow these steps:
524 
5251. Create a new `platform_mcp.py` file (e.g., `spotify_mcp.py`)
5262. Implement platform-specific tools using the `@mcp.tool()` decorator
5273. Add a setup function and integrate it in `server.py`
5284. Update configuration files and documentation
5295. Add tests and examples
530 
531## 📄 License
532 
533This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
534 
535## 🙏 Acknowledgments
536 
537- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the amazing protocol
538- [Anthropic](https://www.anthropic.com/) for Claude and MCP development
539- All the platform APIs that make this integration possible
540 
541## ⭐ Star History
542 
543If you find this project useful, please consider giving it a star on GitHub!
544 
545---
546 
547**Made with ❤️ for connecting your digital life with AI**
548 
549 
550 
551 
552 
553 
554 
555 
556 
557 
558 
559 
560 
561 
562 
563