One zero-dependency command-line tool that reads public social media and hands the result back as clean JSON. Built to be a tool for AI agents — shipped as an MCP server, an HTTP JSON API, and a function-calling schema, all with one identical contract.
Get started Source on GitHub$ ./socialfetch hn search "micro saas revenue" --limit 3 --json { "provider": "hn", "ok": true, "data": { "hits": [ { "title": "I redesigned my funnel and hit $2.5k MRR", "points": 214 }, { "title": "Weekend MVP made $47 on day one", "points": 96 } ] }, "error": null }
Python 3.8+. No pip install, no keys, no accounts.
git clone https://github.com/EdgeAIG/socialfetch.git
cd socialfetch
chmod +x socialfetch
./socialfetch --help
./socialfetch status # which providers work from YOUR network?A bare URL auto-routes — just paste anything and it figures out the provider:
./socialfetch https://t.me/telegram ./socialfetch https://x.com/jack/status/20 ./socialfetch https://www.youtube.com/watch?v=dQw4w9WgXcQ ./socialfetch @user@mastodon.social ./socialfetch https://hnrss.org/frontpage
YouTube downloads (the only optional dependency) ride on yt-dlp:
./socialfetch setup # one-shot installer: yt-dlp (+ ffmpeg check) export SOCIALFETCH_UA="my-agent/1.0" # optional custom User-Agent
Each provider is wired to a real, anonymous, public backend — verified live.
| Provider | Backend | What you get free, no account |
|---|---|---|
x · X/Twitter | FixTweet / vxTwitter | a single tweet by id/URL, a profile by handle |
reddit | Reddit public .json | subreddit listings, user submissions, search, post + comments |
bsky · Bluesky | AT Protocol public API | post search, profiles |
masto · Mastodon | any instance public API | search, profiles, recent statuses |
lemmy | any instance public API | post search, community info |
hn · Hacker News | Algolia HN Search | stories, comments, users, front page |
ig · Instagram | anonymous mobile-feed endpoints | profile, recent posts, a single post — no login |
yt · YouTube | yt-dlp | metadata, search, and downloads: video, audio, mp3, playlists, subtitles |
tg · Telegram | public web preview t.me/s/… | channel meta, messages with views/media (photo, video, file, audio, sticker, poll), pagination + filters — no login |
tiktok | oEmbed endpoint | title + author of a public video by URL |
vimeo | oEmbed endpoint | title, author, duration, thumbnail |
fb · Facebook | oEmbed endpoint (tokenless since June 2026) | public post or video by URL: title, author, embed HTML; fb page = best-effort metadata |
li · LinkedIn | public og: metadata | profile / company / public post by URL: name, headline, experience, education, connections · followers, founded, about — no login |
feed · any RSS/Atom | stdlib XML parser | blogs, news, podcasts, YouTube channel RSS |
./socialfetch manifest prints this as a machine-readable capability list.
Every command returns the same envelope; every failure is honest.
{"provider": "tg", "ok": true, "data": {...}, "error": null}ok true/false; error is always a string on failure.0 success · 1 fetch failed · 2 usage error../socialfetch --json x post 20 == ./socialfetch x post 20 --json../socialfetch hn front ./socialfetch hn search "claude code" --limit 3 --json ./socialfetch reddit sub machinelearning --sort top --limit 10 ./socialfetch reddit search "side projects" --limit 8 ./socialfetch bsky search "climate" --limit 10 ./socialfetch lemmy search "rust" --limit 10 ./socialfetch ig user nasa --limit 5 ./socialfetch tg channel telegram --max 50 ./socialfetch tg post https://t.me/telegram/441 ./socialfetch tg channel telegram --media video --limit 10 ./socialfetch tg channel telegram --media file --ext pdf --limit 10 ./socialfetch tg channel telegram --query "pricing" --limit 10 ./socialfetch tg search telegram "automation" --limit 10 ./socialfetch tg download https://t.me/telegram/441 -o ./dl ./socialfetch tiktok https://www.tiktok.com/@tiktok/video/7106594312292453675 ./socialfetch vimeo https://vimeo.com/22439234 ./socialfetch li profile williamhgates ./socialfetch li company linkedin ./socialfetch fb post https://www.facebook.com/<page>/posts/<id> ./socialfetch fb video https://www.facebook.com/<page>/videos/<id> ./socialfetch feed https://hnrss.org/frontpage ./socialfetch manifest --json
One tool, typed schema — plug into Claude Desktop, Cursor, Claude Code, OpenCode, or any MCP host.
{ "mcpServers": { "socialfetch": {
"command": "python3",
"args": ["/absolute/path/to/socialfetch/socialfetch-mcp"] } } }claude mcp add socialfetch -- python3 /absolute/path/to/socialfetch/socialfetch-mcp
Register the same command in your opencode.json MCP config. Note: OpenCode namespaces MCP tools as socialfetch_socialfetch — call it with a single command string.
{"command": "hn search \"micro saas revenue\" --limit 8 --json"}The tool accepts either a free-form command (bare URL or CLI string) or structured fields (provider, action, target, query, limit, …). Failures map to isError: true.
For agents that prefer HTTP over stdio.
./socialfetch-api # listens on http://0.0.0.0:8099
curl -s localhost:8099/health
curl -s localhost:8099/manifest
curl -s -X POST localhost:8099/call -H 'Content-Type: application/json' \
-d '{"command": "https://t.me/telegram"}'
curl -s -X POST localhost:8099/call -H 'Content-Type: application/json' \
-d '{"provider": "hn", "action": "search", "query": "rust", "limit": 3}'tools.json is a ready-made OpenAI/Anthropic tools definition — register it and the model calls socialfetch with structured arguments, the same ones the MCP server accepts.
command — bare URL or CLI string (overrides everything)provider — x · reddit · bsky · masto · lemmy · hn · ig · yt · tg · tiktok · vimeo · feed · url · manifest · status · setupaction — post · user · sub · search · community · front · info · download · channeltarget / query — the subject or search textlimit, sort, instance, type, tags, timeoutmax, before, after — Telegram paginationmedia, has_media, ext, query, author — Telegram filtersbotcmd — Telegram Bot API method (me/chat/file/photo; env SOCIALFETCH_TG_BOT_TOKEN)audio, mp3, format, out, items, subs, playlist — YouTube downloadsNo posting, liking, or following. Public data only. By design.
./socialfetch yt info <url> # title, channel, duration, views, description ./socialfetch yt info <playlist-url> # list a playlist ./socialfetch yt info https://www.youtube.com/@MrBeast ./socialfetch yt search "claude code tutorial" ./socialfetch yt download <url> -o ./out # best video+audio (needs ffmpeg) ./socialfetch yt download <url> --audio # audio only → .m4a (no ffmpeg) ./socialfetch yt download <url> --mp3 # → .mp3 (needs ffmpeg) ./socialfetch yt download <url> --format "best[height<=720]" ./socialfetch yt download <playlist-url> --items 1-5 ./socialfetch yt download <url> --subs
--items supports 1-5, 1,3,5, 3: (yt-dlp syntax). Playlists download in full by default; --no-playlist takes only the first video.
FAIL in ./socialfetch status. That's network, not auth.t.me/s/…. Groups/private channels need a logged-in client, which is out of scope. Files/documents expose no direct download URL on the preview (name+size only).tg bot (optional env token) adds chat metadata, member counts and file URLs — not search.fb post <url> / fb video <url> (Meta oEmbed, tokenless since June 2026) — and Meta blocks datacenter IPs on it, so it works from home but shows FAIL in a sandbox.og: metadata (works even from datacenter IPs); feeds, search, comments, reactions, messages and private profiles are login-walled. The official API is partner-gated../socialfetch status is your friend.Products like Monid (monid.ai/SKILL.md) look like this but require an account + API key + paid balance — they're middlemen reselling Apify/Harvest scraper runs at fractions of a cent per item. socialfetch gives you the genuinely-free, genuinely-no-account subset directly, by talking to the public endpoints yourself.
socialfetch/ # the CLI (single file, stdlib only) socialfetch-mcp # MCP server (exposes `socialfetch` as an agent tool) socialfetch-api # HTTP JSON API (GET /health, /manifest; POST /call) tools.json # OpenAI/Anthropic function-calling schema mcp-config.json # ready-made MCP client config snippet SKILL.md # agent skill for auto-use in a coding harness docs/ # this documentation site (GitHub Pages)