██████╗ ██████╗ ██████╗██╗ █████╗ ██╗ ██████╗ █████╗ ██████╗ █████╗ ██████╗ ██╔════╝ ██╔═══██╗██╔════╝██║██╔══██╗██║ ██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔══██╗ ╚█████╗ ██║ ██║██║ ██║███████║██║ ██████╔╝███████║██║ ██║███████║██████╔╝ ╚═══██╗ ██║ ██║██║ ██║██╔══██║██║ ██╔══██╗██╔══██║██║ ██║██╔══██║██╔══██╗ ██████╔╝ ╚██████╔╝╚██████╗██║██║ ██║███████╗██║ ██║██║ ██║██████╔╝██║ ██║██║ ██║ ╚═════╝ ╚═════╝ ╚═════╝╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝
One sentence, scan multiple social platforms.
AI-native cross-platform social search engine — powered by MCP & TikHub
🌐 中文文档 | English
Searching for tech interview experiences, industry trends, or community discussions across Chinese social platforms is painful:
- Fragmented — Xiaohongshu, Zhihu, Bilibili... each has its own search box and result format
- Repetitive — Same keyword typed 3+ times, same content scrolled past on different platforms
- Ephemeral — Tabs get closed, results get lost, no persistent record
SocialRadar solves this with a single unified search interface that plugs directly into your AI-powered workflow.
"Search Xiaohongshu and Zhihu for Agentic RL interview experiences."
"Find the latest discussions about DeepSeek-R1 training pipeline."
"What are people saying about LLM algorithm job market in 2025?"
One sentence. Cross-platform search. Structured results. Right inside your IDE.
| 🔄 Traditional Workflow | ⚡ With SocialRadar |
|
❌ Open 2+ apps / websites manually ❌ Copy & paste results by hand ❌ Switch tabs and lose context ❌ No AI integration ❌ Search one platform at a time ❌ Results scattered, hard to compare |
✅ One natural-language sentence ✅ Auto cross-platform aggregation ✅ Results persisted in conversation ✅ Native Claude Code MCP support ✅ All platforms in one request ✅ Normalized, ranked, deduped output |
| Multi-Platform Unified search across Xiaohongshu & Zhihu with one query |
AI-Native Claude Code MCP deep integration speak, don't type |
Hot-Pluggable Add any platform via YAML config + one normalizer function |
Structured Output Schema normalization cross-platform dedup engagement-based ranking |
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.11+ | asyncio, type hints support |
| TikHub API Key | — | Register for free |
git clone https://github.com/your-username/SocialRadar.git && cd SocialRadar
pip install -e .
cp .env.example .envEdit .env with your credentials:
# TikHub API Key — get it from https://tikhub.io
TIKHUB_API_KEY=tikhub_xxxxxxxxxxxxxVerify the installation:
social-radar platforms
# Should list: Xiaohongshu (小红书), Zhihu (知乎)Add to Claude Code settings.json:
{
"mcpServers": {
"social-radar": {
"command": "python",
"args": ["-m", "social_radar.server"],
"env": { "TIKHUB_API_KEY": "tikhub_xxxxxxxxxxxxx" }
}
}
}Restart Claude Code. Now you have 3 new tools available via natural conversation:
| Tool | Description | When to Use |
|---|---|---|
social_radar_search |
Cross-platform search | General queries across all platforms |
social_radar_xiaohongshu |
Xiaohongshu-only search | Interview experiences, career tips |
social_radar_zhihu |
Zhihu-only search | Deep technical discussions, Q&A |
Example conversations:
> Search Xiaohongshu for LLM algorithm interview preparation tips.
> What are the latest discussions on Zhihu about GRPO vs PPO training?
> Find me Xiaohongshu posts about agentic RL jobs in China, and also
search Zhihu for technical discussions on the same topic.
# Basic cross-platform search
social-radar search "agentic RL interview"
# Platform-specific
social-radar search "RLHF training pipeline" -p zhihu
social-radar search "大模型面试经验" -p xiaohongshu
# Advanced
social-radar search "DeepSeek-R1 architecture" -p xiaohongshu -n 20
social-radar search "MCP protocol" --json | jq '.[] | {title, url, likes}'
social-radar search "reward hacking" -p zhihu,xiaohongshu
# Utility
social-radar platforms # list all supported platforms
social-radar search --help # full CLI reference📟 Terminal Preview
╭─────────────────── Search Results: 「agentic RL interview」 ───────────────────╮
│ # │ Platform │ Title │ Author │ Likes │
│ 1 │ Xiaohongshu │ Agent方向大模型面试总结… │ AI求职笔记 │ 1.2k │
│ 2 │ Zhihu │ 如何看待 agentic RL 成为新热点？ │ Wang XX │ 856 │
│ 3 │ Xiaohongshu │ RL算法岗面试经验全分享 │ ML_Engineer │ 623 │
│ 4 │ Zhihu │ GRPO 算法原理解析与面试题整理 │ Li-Paper │ 491 │
│ 5 │ Xiaohongshu │ 字节跳动AML面试回顾 │ OfferCat │ 387 │
└──────────────────────────────────────────────────────────────────────────────┘
15 results total · deduped from 23 raw across 2 platforms
Each platform is defined as a YAML block. Here's the anatomy:
xiaohongshu: # platform key (used in -p flag)
name: 小红书 # display name
endpoint: https://mcp.tikhub.io/... # TikHub MCP endpoint
search_tool: xiaohongshu_app_v2_search_notes # primary search tool
search_params: # default parameters
keyword: "{query}" # {query} = user input placeholder
page: 1
sort_type: general
note_type: 不限
time_filter: 不限
note_link_template: "https://www.xiaohongshu.com/explore/{note_id}"
max_results: 20| Variable | Required | Description |
|---|---|---|
TIKHUB_API_KEY |
Yes | TikHub API authentication key |
SOCIAL_RADAR_CONFIG |
No | Custom YAML config path (default: config/platforms.yaml) |
SOCIAL_RADAR_MAX_RESULTS |
No | Override max results per platform (default: 20) |
Step 1 — Add config block in config/platforms.yaml:
bilibili:
name: B站
endpoint: https://mcp.tikhub.io/bilibili/mcp
search_tool: bilibili_web_search_videos
search_params:
keyword: "{query}"
page: 1Step 2 — Add a normalizer in src/social_radar/aggregator.py:
def normalize_bilibili(raw: dict, platform_cfg) -> list[SearchResult]:
"""Parse Bilibili search response into unified SearchResult."""
results = []
items = raw.get("data", {}).get("items", [])
for item in items:
results.append(SearchResult(
platform="bilibili",
platform_name="B站",
title=item.get("title", ""),
url=item.get("url", ""),
summary=item.get("description", ""),
author=item.get("owner", {}).get("name", ""),
likes=item.get("stat", {}).get("like", 0),
))
return resultsThat's it. The new platform appears automatically in CLI and MCP tools.
| Layer | Modules | Responsibility |
|---|---|---|
| Interface | server.py · cli.py |
Dual entrypoints: MCP stdio server for Claude Code + standalone Typer CLI |
| Engine | platforms.py · client.py · aggregator.py |
YAML-driven platform registry, SSE protocol client, cross-platform result merging |
| Gateway | TikHub MCP endpoints | Per-platform MCP servers exposing search tools via standardized SSE protocol |
User Input → [server.py / cli.py] → [platforms.py] → [client.py] → TikHub MCP
↳ Xiaohongshu API
↳ Zhihu API
Result ← [aggregator.py] ← normalize ← dedup ← rank ← [client.py]
- Why SSE over WebSocket? — TikHub uses standard MCP SSE protocol. Single-direction streaming is sufficient for request-response search patterns; bidirectional channels add complexity with no benefit here.
- Why separate normalizer per platform? — Each platform returns different JSON schemas. Isolating normalizers keeps them testable and replaceable without touching the core engine.
- Why YAML for platform config? — Human-readable, diff-friendly, no code change needed to adjust parameters. Users can customize search defaults without touching Python.
Focused on Chinese tech-community platforms where AI practitioners share knowledge.
All 16 TikHub platforms are extensible — see how to add one.
xiaohongshu
Search tools: app_v2_search_notes · web_v2_fetch_search_notesContent types: Notes, images, video notes Best for: Interview experiences · career tips · tech explainers · industry gossip Notes: Results favor engagement metrics (likes, saves, comments) |
zhihu
Search tools: article_search_v3 · ai_search · topic_search_v3Content types: Articles, answers, columns, topics Best for: Deep technical discussions · Q&A · paper analysis · industry analysis Notes: ai_search provides LLM-summarized answers with citations
|
Available via TikHub (config-ready):
Douyin · Bilibili · Weibo · YouTube · Reddit · Twitter · LinkedIn · Kuaishou · Threads · WeChat
SocialRadar/
├── src/social_radar/
│ ├── __init__.py # Package metadata (v0.1.0)
│ ├── server.py # MCP Server — Claude Code entrypoint
│ ├── cli.py # CLI — standalone Typer entrypoint
│ ├── client.py # TikHub SSE client (init → tools/call)
│ ├── platforms.py # YAML config loader + platform data model
│ └── aggregator.py # Schema normalization + dedup + ranking
├── config/
│ └── platforms.yaml # Platform definitions (hot-pluggable)
├── docs/
│ └── images/ # Architecture & flow diagrams
├── pyproject.toml # Python project metadata
├── .env.example # API key template
├── .gitignore # Excludes .env, __pycache__, etc.
├── LICENSE # MIT License
├── README.md # English docs (this file)
└── README_CN.md # 中文文档
| Milestone | Status | Description |
|---|---|---|
| v0.1 — Core | ✅ Done | Xiaohongshu + Zhihu search, MCP Server, CLI, result aggregation |
| v0.2 — Richer Output | 🚧 Planned | Note detail fetching, comment extraction, author profile enrichment |
| v0.3 — More Platforms | 📋 Planned | Bilibili, Weibo, Douyin normalizer support |
| v0.4 — Smart Search | 💡 Idea | AI-powered query expansion, search term suggestions, multi-round refinement |
| v0.5 — Persistence | 💡 Idea | Search history, saved queries, Markdown/JSON export |
| v1.0 — Production | 🎯 Target | Test coverage >80%, CI/CD, Docker image, comprehensive docs |
How is SocialRadar different from using TikHub MCP directly?
TikHub exposes one MCP endpoint per platform. You would need to configure 16 separate MCP servers and remember 200+ tool names. SocialRadar provides a single unified entrypoint with 3 intuitive tools: search all platforms, or target a specific one. Cross-platform dedup, format normalization, and ranking happen automatically.
What affects search result quality?
SocialRadar is a client-side aggregation layer. Result quality depends on TikHub's upstream APIs and each platform's native search algorithm. We add value by:
(1) Normalizing heterogeneous response formats into a unified schema
(2) Cross-platform dedup by title similarity
(3) Engagement-based default ranking (likes, comments, collects)
(4) Preserving raw response data for advanced users
Is my personal data involved?
No. SocialRadar calls TikHub's public API endpoints. No social media account login, no browser cookies, no personal data access. Your API key is the only credential and is stored locally in
.env (excluded from git by .gitignore).
Can I use it without Claude Code?
Yes. The CLI mode (
social-radar search ...) works independently in any terminal. The MCP server is optional — it's an additional entrypoint for Claude Code users who want AI-integrated search.
What's the rate limit?
Rate limits are determined by your TikHub subscription plan. SocialRadar itself adds no additional throttling. The free tier typically supports dozens of searches per minute — more than enough for individual use.
How do I debug a failed search?
Checklist:
1. Verify
TIKHUB_API_KEY is set correctly in .env2. Run
social-radar platforms to confirm config loading3. Check your TikHub dashboard for API quota status
4. Run with
--json flag to inspect raw API responses
All contributions are welcome — from bug reports to new platform normalizers.
| Type | How | Example |
|---|---|---|
| 🐛 Bug | Open an Issue | Search returns empty / crash on specific keyword |
| 🔌 Platform | PR a normalizer | Add Weibo / Bilibili / Douyin support |
| 📝 Docs | PR the README | Fix typos, add usage examples, translate |
| ✨ Feature | Discuss in Issue first | Scheduled search, Markdown export, etc. |
Before submitting a PR: ensure pip install -e . succeeds and the CLI works with your changes.
MIT License © 2026
Built with ❤️ for the AI community · Powered by TikHub MCP