<h1 align="center">hidrix-tools</h1>

<p align="center"> MCP tool server that gives any AI agent the ability to search, scrape, and analyze content across the internet. </p>

---

What is hidrix-tools?

AI agents like Claude, OpenClaw, Hermes, Cursor, and pi can read files and write code — but they can't search the web, read social media, or scrape data on their own.

hidrix-tools fixes that. It's an MCP server that provides tools for web search, social media search, Facebook scraping, content analysis, and more. Plug it into any agent that supports MCP — no vendor lock-in.

Your AI Agent                    hidrix-tools                     Internet
┌──────────┐     MCP protocol    ┌──────────────┐                ┌─────────┐
│ Claude   │ ◄─────────────────► │ web_search   │ ◄────────────► │ Brave   │
│ OpenClaw │                     │ x_search     │                │ X/Twitter│
│ Hermes   │                     │ reddit_search│                │ Reddit  │
│ Cursor   │                     │ facebook_    │                │ Facebook│
│ pi       │                     │   scraper    │                │ YouTube │
│ Codex    │                     │ content_     │                │ TikTok  │
│ ...      │                     │   scorer     │                │ Meta Ads│
└──────────┘                     └──────────────┘                └─────────┘

Why use hidrix-tools?

| Without hidrix-tools | With hidrix-tools | |---|---| | Agent can only read local files | Agent can search web, read articles, scrape social media | | "I don't have access to the internet" | "Here are the top 10 Reddit posts about your topic this week" | | Manual copy-paste research | Agent autonomously gathers data from 7+ platforms | | No competitive intelligence | Agent scrapes competitor FB pages, analyzes engagement patterns | | One platform at a time | Cross-platform research in a single conversation |

Compatible agents

| Agent / Platform | Setup | Status | |---|---|---| | Claude Code / Claude Desktop | settings.json → mcpServers | ✅ Tested | | pi | Native extension (no MCP) | ✅ Tested | | OpenClaw | openclaw.json → mcp_servers | ✅ Compatible | | Hermes Agent | config.yaml → mcp_servers | ✅ Compatible | | Cursor | MCP settings | ✅ Compatible | | Codex CLI | MCP config | ✅ Compatible | | Any MCP client | stdio transport | ✅ |

Tools

Search

| Tool | Source | What it does | |------|--------|-------------| | web_search | Brave Search | Search the web — titles, URLs, descriptions | | x_search | GetXAPI / RapidAPI | Search X/Twitter with engagement data (likes, retweets, views) | | x_thread_reader | GetXAPI | Read full X threads, articles, and tweet replies | | x_user_posts | GetXAPI | Get recent posts from a specific X user with engagement | | reddit_search | RapidAPI | Search Reddit with full text and engagement data | | reddit_thread_reader | Reddit JSON API (free) | Read full post + comment tree | | reddit_subreddit_top | Reddit JSON API (free) | Top posts from any subreddit by time range | | youtube_search | RapidAPI | Search YouTube videos | | tiktok_search | RapidAPI | Search TikTok videos |

Scrape & Fetch

| Tool | Source | What it does | |------|--------|-------------| | web_fetch | Mozilla Readability | Fetch any URL → clean readable markdown | | facebook_scraper | Apify + Meta API | Scrape FB groups, pages, keyword search, or Meta Ad Library |

Analyze

| Tool | Source | What it does | |------|--------|-------------| | content_scorer | Built-in | Score and rank posts by weighted engagement + time-decay | | content_analyzer | Built-in | Topic clusters, content patterns, timing trends, author leaderboard |

| Tool | Source | What it does | |------|--------|-------------| | linkedin_search | Apify (no login) | Search LinkedIn posts by keyword with engagement data | | linkedin_profile | Apify (no login) | Get recent posts from a LinkedIn profile |

Intel

| Tool | Source | What it does | |------|--------|-------------| | similarweb | RapidAPI | Website traffic, rank, engagement analytics |

Storage & Automation

| Tool | Source | What it does | |------|--------|-------------| | data_store | SQLite (built-in) | Save/query scraped posts, dedup, run history, storage stats |

Real-world use cases

🔍 Research agent

"Find top 10 posts about AI agents on Reddit this week, compare with X/Twitter, summarize the trends"

Agent uses: reddit_search → x_search → content_analyzer

📊 Content pipeline

"Scrape 5 Facebook groups about marketing VN, rank top 100 posts by engagement, analyze patterns"

Agent uses: facebook_scraper (group mode) → content_scorer → content_analyzer

🕵️ Competitive intelligence

"What ads is competitor X running on Facebook? What's their messaging strategy?"

Agent uses: facebook_scraper (ads mode) → Meta Ad Library API (free)

📰 Article research

"Read these 5 articles and summarize the key insights"

Agent uses: web_fetch (for each URL)

📈 Market research

"What are people saying about product X across Reddit, X, and YouTube?"

Agent uses: reddit_search + x_search + youtube_search → content_analyzer

🏆 Top content discovery

"Find the most viral posts in this Facebook group this month"

Agent uses: facebook_scraper → content_scorer (sort by engagement)

Install

Quick setup

git clone https://github.com/sonpiaz/hidrix-tools.git ~/.hidrix-tools
cd ~/.hidrix-tools && bun install && cp .env.example .env
# Add your API keys to .env

Connect to your agent

Claude Code — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "hidrix-tools": {
      "command": "bun",
      "args": ["run", "/path/to/hidrix-tools/server.ts"]
    }
  }
}

OpenClaw — add to openclaw.json:

mcp_servers:
  hidrix-tools:
    command: "bun"
    args: ["run", "/path/to/hidrix-tools/server.ts"]

Hermes Agent — add to ~/.hermes/config.yaml:

mcp_servers:
  hidrix-tools:
    command: "bun"
    args: ["run", "/path/to/hidrix-tools/server.ts"]

pi (coding agent) — copy extension:

cp -r integrations/pi-extension ~/.pi/agent/extensions/hidrix-tools
# Then /reload in pi

See integrations/pi-extension/README.md for details.

Standalone (any MCP client):

bun run server.ts

API Keys

Tools are auto-skipped if their API keys are missing — only configure what you need.

| Key | Tools | Free Tier | Get it | |-----|-------|-----------|--------| | BRAVE_API_KEY | web_search | 2,000 queries/month | api.search.brave.com | | GETXAPI_KEY | x_search, x_thread_reader, x_user_posts | $0.001/call, no subscription | getxapi.com | | RAPIDAPI_KEY | x_search (fallback), reddit_search, youtube_search, tiktok_search | Varies | rapidapi.com | | SUPADATA_API_KEY | youtube_channel (primary) | Paid from $9/mo | supadata.ai | | APIFY_API_TOKEN | facebook_scraper (group/page/search) | $5/month credit | console.apify.com | | META_ADS_ACCESS_TOKEN | facebook_scraper (ads mode) | Free, unlimited | facebook.com/ads/library/api |

Add your own tool

Tools are auto-discovered — no changes to server.ts needed.

cp -r tools/_template tools/your-tool-name
# Edit tools/your-tool-name/index.ts
bun run server.ts
# [hidrix-tools] ✓ your_tool_name

See docs/adding-a-tool.md for the full guide.

Project structure

hidrix-tools/
├── server.ts                  — MCP server, auto-discovers tools
├── tools/
│   ├── _template/             — Copy this to create a new tool
│   ├── web-search/            — Brave Search
│   ├── web-fetch/             — URL → markdown
│   ├── x-search/              — X/Twitter search (GetXAPI + RapidAPI fallback)
│   ├── x-thread-reader/       — Read X threads & articles
│   ├── x-user-posts/          — User timeline with engagement
│   ├── reddit-search/         — Reddit search (upgraded)
│   ├── reddit-thread-reader/  — Full post + comment tree (free API)
│   ├── reddit-subreddit-top/  — Subreddit top posts (free API)
│   ├── youtube-search/        — YouTube search
│   ├── tiktok-search/         — TikTok search
│   ├── similarweb/            — Traffic analytics
│   ├── facebook-scraper/      — FB groups, pages, search, ads
│   ├── content-scorer/        — Engagement scoring + ranking
│   └── content-analyzer/      — Topic/pattern/trend analysis
├── lib/
│   ├── tool-registry.ts       — Auto-discovery engine
│   ├── rapidapi.ts            — Shared RapidAPI client
│   ├── getxapi.ts             — GetXAPI client (X/Twitter)
│   ├── apify.ts               — Apify REST client
│   ├── meta-ads.ts            — Meta Ad Library API client
│   └── readability.ts         — HTML → markdown extraction
└── docs/
    ├── adding-a-tool.md       — Tool authoring guide
    ├── feedback-and-bug-reporting.md — Bug reporting standards
    ├── known-issues.md        — Tracked limitations
    └── ROADMAP.md             — Development roadmap

Docs

| Doc | Description | |-----|-------------| | Adding a tool | How to create a new tool | | Feedback & bug reporting | Standards for detecting and reporting issues | | Known issues | Tracked provider limitations and quirks | | Roadmap | Development roadmap (X upgrade, Reddit upgrade, LinkedIn, extensions) |

Tech stack

| Technology | Purpose | |-----------|---------| | Bun | Runtime | | TypeScript | Language | | MCP SDK | Agent protocol | | Brave Search | Web search | | Mozilla Readability | Content extraction | | Apify | Facebook scraping | | Meta Ad Library API | Ad intelligence (free) |

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

When reporting bugs, follow docs/feedback-and-bug-reporting.md.

affiliate-skills — 45 AI agent skills
content-pipeline — AI-powered LinkedIn content generation
Kapt — macOS screenshot tool with annotation & OCR
Yap — Push-to-talk dictation for macOS

License

MIT — see LICENSE for details.

---

<p align="center">Built by <a href="https://github.com/sonpiaz">Son Piaz</a></p>

hidrix-tools