Metadata-Version: 2.4
Name: supermcp
Version: 0.10.0
Summary: Reddit, Twitter, LinkedIn, BlackHatWorld, Dev.to, Medium & Google Trends/News MCP server for AI tools. Markdown output, reads your Chrome login session.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: gnews>=0.4.3
Requires-Dist: httpx>=0.28.1
Requires-Dist: playwright>=1.58.0
Requires-Dist: pycookiecheat>=0.8.0
Requires-Dist: trendspy>=0.1.6
Description-Content-Type: text/markdown

# SuperMCP

Reddit, Twitter, LinkedIn, Pinterest, BlackHatWorld, Dev.to, Medium, and Google Trends/News — one MCP server for Claude Code, Cursor, and any AI tool that speaks MCP.

Uses your Chrome login session automatically — no API keys, no OAuth dance, no manual cookie copying. Just be logged into the sites you want to read in Chrome.

**Includes [LinkedIn MCP](#linkedin-mcp), [Reddit MCP](#reddit-mcp), [Twitter MCP (X)](#twitter--x-mcp), [Pinterest MCP](#pinterest-mcp), [Medium MCP](#medium-mcp), [Dev.to MCP](#devto-mcp), [BlackHatWorld MCP](#blackhatworld-mcp), and [Google Trends/News MCP](#google-trends--news-mcp) — all in one install.**

## Setup

The whole setup is three steps: install the package, get a free API key, then point your AI tool at it. If you're walking an AI assistant through this (Claude, Cursor, Copilot), it can follow these steps verbatim — the paths and JSON are exact, not illustrative.

### 1. Install the package

Pick whichever you already have. They all produce a `supermcp` command on your PATH.

```bash
uv tool install supermcp     # preferred — isolated, no PATH conflicts
pipx install supermcp        # also fine
pip install --user supermcp  # works everywhere
```

Confirm it's reachable: `which supermcp` (macOS/Linux) or `where supermcp` (Windows). Note the absolute path — you may need it in step 3 if your AI tool can't find `supermcp` on its own PATH.

### 2. Get your API key

```bash
supermcp setup
```

This opens a browser, signs you in, and writes the key to a local config file. It's **interactive** — run it in your own terminal, not from inside another tool's shell, or it will hang waiting for the browser handshake. The free tier (100 requests/day) needs no payment info.

You can do step 3 in parallel; the key is only read when a tool actually runs, not when the client starts.

### 3. Connect it to your AI tool

Find your client below. The JSON shape is the same everywhere — only the file path changes.

#### Claude Code

```bash
claude mcp add supermcp -- supermcp
```

Verify with `claude mcp list`. New Claude Code sessions pick it up automatically; no restart needed.

#### Claude Desktop

Open the config file for your OS:

| OS      | Path                                                                  |
|---------|-----------------------------------------------------------------------|
| macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json`     |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json`                         |
| Linux   | `~/.config/Claude/claude_desktop_config.json`                         |

You can also reach it from inside the app: **Settings → Developer → Edit Config**.

If the file is empty or doesn't exist, the full contents should be:

```json
{
  "mcpServers": {
    "supermcp": {
      "command": "supermcp"
    }
  }
}
```

If the file already has content (it usually does — at least a `preferences` block, and possibly other `mcpServers`), **merge, don't replace**. Read the file, add the `supermcp` entry inside `mcpServers` alongside any existing servers, keep every other top-level key untouched, and write it back. If the JSON doesn't parse, stop and fix it by hand — overwriting a malformed config silently destroys other tools' settings.

Then **fully quit and relaunch Claude Desktop**: Cmd+Q on macOS, right-click the tray icon → Quit on Windows/Linux. Closing the window is not enough — the background process keeps running and won't re-read the config.

If you see `spawn supermcp ENOENT` after restart, Claude Desktop couldn't find `supermcp` on its PATH (common on macOS where GUI apps don't inherit shell PATH). Two fixes — either works:

```json
"supermcp": { "command": "/absolute/path/from/which-supermcp" }
```

or use `uvx`, which finds and runs the package without needing a global install:

```json
"supermcp": {
  "command": "uvx",
  "args": ["--from", "supermcp", "supermcp"]
}
```

#### Cursor

Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` inside your project (project-scoped). Same merge rules as Claude Desktop: read, add the `supermcp` entry inside `mcpServers`, write back.

```json
{
  "mcpServers": {
    "supermcp": { "command": "supermcp" }
  }
}
```

Cursor reloads MCP servers on save; if a tool call still fails, restart Cursor.

#### Windsurf, Cline, Continue, Copilot Agent, and other MCP clients

They all use the same JSON shape — only the config path differs. Check your client's docs for the path, then merge in:

```json
{
  "mcpServers": {
    "supermcp": { "command": "supermcp" }
  }
}
```

If the client errors with ENOENT, use the absolute-path or `uvx` fallback shown in the Claude Desktop section.

### 4. Verify

In your AI tool, ask it to use a SuperMCP tool — for example, *"search reddit for posts about buildinpublic and MRR"*. You should get back a markdown-formatted list of posts. If something goes wrong:

| Error                 | Cause                                        | Fix                                                         |
|-----------------------|----------------------------------------------|-------------------------------------------------------------|
| `no API key`          | Step 2 wasn't completed                      | Run `supermcp setup` in your terminal                       |
| `spawn ... ENOENT`    | Client can't find `supermcp` on its PATH     | Use the absolute path or the `uvx` form (see Claude Desktop)|
| `Can't read Chrome cookies` | Chrome missing, or Keychain access denied | Install Chrome; on macOS, approve the Keychain prompt    |
| Reddit / X / LinkedIn returns nothing | Not logged in on this machine      | Open the site in Chrome and sign in, then retry             |

## How it works

```
Claude / Cursor ←stdio→ SuperMCP (Python, FastMCP)
                          │
                          ├── Playwright (headless Chromium)
                          │     ├── reddit.com         (Chrome login)
                          │     ├── x.com              (Chrome login)
                          │     ├── linkedin.com       (Chrome login)
                          │     ├── pinterest.com      (Chrome login optional, anonymous fallback)
                          │     ├── medium.com         (Chrome login, search only)
                          │     └── blackhatworld.com  (no login, search via browser)
                          │
                          └── Direct httpx (no browser)
                                ├── dev.to API + Algolia search
                                ├── Medium RSS feeds (tag, user)
                                ├── BlackHatWorld threads + RSS
                                ├── Google Trends   (trendspy)
                                └── Google News     (gnews)
```

No browser extension. No WebSocket bridge. SuperMCP launches a headless Chromium and reuses your existing Chrome cookies for sites that need login.

All tools return **token-efficient markdown** (~35% smaller than JSON, native to Claude) with stable IDs and URLs so the LLM can chain follow-up calls.

## Tools (33 total)

### Reddit MCP
Search Reddit, read posts with their comment trees, list subreddit feeds (hot/top/new/rising), and pull a user's recent activity — all without registering a Reddit API app or paying for the new API tiers. Reads your existing reddit.com Chrome session.

| Tool | Description |
|------|-------------|
| `reddit_search` | Search all of Reddit |
| `reddit_search_subreddit` | Search within a specific subreddit |
| `reddit_get_post` | Get a post with its top comments |
| `reddit_get_subreddit_posts` | List posts (hot/top/new/rising) |
| `reddit_get_user_activity` | Get a user's recent posts and comments |

### Twitter / X MCP
Search tweets, fetch a tweet plus its reply tree, and pull a user's recent timeline. Bypasses the X API's $200/month minimum tier — uses your existing x.com Chrome session.

| Tool | Description |
|------|-------------|
| `twitter_search` | Search tweets |
| `twitter_get_tweet` | Get a tweet with its replies |
| `twitter_get_user_tweets` | Get a user's recent tweets |

### LinkedIn MCP
LinkedIn pain-point mining and B2B research from inside Claude or Cursor. Search posts by keyword, pull your algorithmic home feed, and read comments on any specific post — without LinkedIn's enterprise Marketing API, Phantombuster, or any paid scraper. Uses your linkedin.com Chrome session.

| Tool | Description |
|------|-------------|
| `linkedin_search` | Search posts by keyword (great for pain-point research) |
| `linkedin_feed` | Posts from your home feed |
| `linkedin_post_comments` | Comments on a specific post |

**Use cases:** B2B pain-point mining ("find SaaS founders complaining about onboarding"), competitor research, prospecting, content-trend monitoring, audience research.

### Dev.to MCP
Search Dev.to articles via Algolia, fetch trending posts, and pull article comment threads. No login needed — uses Dev.to's public API.

| Tool | Description |
|------|-------------|
| `devto_search` | Search articles via Algolia |
| `devto_trending` | Trending articles (overall or by tag) |
| `devto_article` | Article + nested comments |
| `devto_user_articles` | A user's published articles |

### Medium MCP
Search Medium articles (login recommended for full results), and follow tag/user feeds via RSS — no Medium Partner API required.

| Tool | Description |
|------|-------------|
| `medium_search` | Search articles (login recommended) |
| `medium_tag_feed` | Latest articles by tag (RSS, no login) |
| `medium_user_feed` | A user's latest articles (RSS, no login) |

### BlackHatWorld MCP
Mine SEO, affiliate, and digital-marketing pain points from BlackHatWorld threads. Headless browser handles Cloudflare; structured metadata included.

| Tool | Description |
|------|-------------|
| `bhw_search` | Search posts (SEO/affiliate/marketing pain points) |
| `bhw_get_thread` | Thread with OP + replies, structured metadata |
| `bhw_latest` | Latest posts site-wide via RSS |

### Google Trends & News MCP
Trending search terms by region, Google News search, and topical news feeds — all without API keys.

| Tool | Description |
|------|-------------|
| `trends_get_trending` | Trending search terms by region |
| `news_search` | Search Google News by keyword |
| `news_top` | Top/trending news stories |
| `news_by_topic` | News by category (TECHNOLOGY, SPORTS, etc.) |

### Pinterest MCP
Pinterest trend research, visual content discovery, and competitor/brand analysis from inside Claude or Cursor. Search pins, drill into a pin's metadata and comments, pull a user's recent pins and boards, browse the contents of a specific board, and surface trending Pinterest searches. Includes a separate image-download tool that caches images locally so Claude can read them with its vision capability. Reads your pinterest.com Chrome session if present (better search results) but works anonymously for public content.

| Tool | Description |
|------|-------------|
| `pinterest_search` | Search pins by keyword |
| `pinterest_get_pin` | A pin with title, image, source, top comments |
| `pinterest_get_user_pins` | A user's recent pins |
| `pinterest_get_user_boards` | A user's board list |
| `pinterest_get_board` | Pins inside a specific board |
| `pinterest_trends` | Top trending Pinterest searches (or insights for a keyword) |
| `pinterest_download_pin_image` | Download a pin's image to local cache for vision analysis |

**Use cases:** trend & keyword research for marketers and content writers, visual content discovery (pin images Claude can actually look at), brand/competitor research on what's being pinned.

### Utility
| Tool | Description |
|------|-------------|
| `supermcp_status` | Check login status and source readiness |

## Output format

Every tool returns markdown structured like this:

```markdown
## Post 1 · r/buildinpublic
**Built my SaaS in 3 weekends, hit $5k MRR**
by u/alice · 542↑ · 87💬 · 2026-04-29 · flair: AMA
https://reddit.com/r/buildinpublic/comments/abc123/built/
**id:** abc123

I had this idea for...
```

Stable IDs and URLs are always preserved so Claude can chain follow-up calls
(`reddit_get_post(post_id="abc123")` to read full comments). Errors begin with
`**Error:**` for easy detection.

## Pricing

- **Free:** 100 requests/day
- **Unlimited:** $9 one-time at [webmatrices.com/supermcp](https://webmatrices.com/supermcp)

## Troubleshooting

See the [Verify table in Setup](#4-verify) for the common install errors (`no API key`, `ENOENT`, Chrome cookies, missing login).

A few extras that only come up at runtime:

- **BHW search returns nothing** — Cloudflare occasionally rate-limits the headless browser. Retry, or use `bhw_latest` + `bhw_get_thread` to drill down manually.
- **Medium search results look thin** — Medium gates most search behind login; sign into medium.com in Chrome for full results.

## Privacy

SuperMCP runs entirely on your machine. Cookies stay in Chrome — they're read fresh from disk each request and never leave your laptop. The only network call to Webmatrices is the API key validation (so we can rate-limit the free tier).

## FAQ

**What is a LinkedIn MCP server?**
An MCP (Model Context Protocol) server that lets Claude, Cursor, or any MCP-compatible AI tool read LinkedIn directly — search posts, pull your feed, fetch comments. SuperMCP's LinkedIn MCP uses your existing LinkedIn login session in Chrome, so there are no API keys to register and no OAuth flow.

**How is this different from Phantombuster, Apify, or the LinkedIn Marketing API?**
The LinkedIn Marketing API is enterprise-gated (you need an approved use case). Phantombuster starts at $69/month. Apify and Bright Data charge per request. SuperMCP runs locally on your machine using your own session — $0 for 100 requests/day, $9 one-time for unlimited.

**Does the Reddit MCP need a Reddit API key?**
No. The Reddit MCP uses your existing reddit.com Chrome session. No client secret, no OAuth refresh tokens, no API tier limits.

**Does the Twitter / X MCP need an X API subscription?**
No. The X API now starts at $200/month for the Basic tier. SuperMCP's Twitter MCP uses your existing x.com Chrome session — no subscription needed.

**Which AI tools support this?**
Any MCP-compatible client: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, GitHub Copilot Agent, Continue, and others. SuperMCP is a standard stdio MCP server.

**Is it open source?**
Yes — MIT licensed. Audit the code yourself before installing (recommended for any tool that touches your browser session).

**Where do I get an API key?**
Run `supermcp setup` after `pip install supermcp`. Free tier (100 requests/day) is automatic. Unlimited tier is $9 one-time at [webmatrices.com/supermcp](https://webmatrices.com/supermcp).

## Made by [Webmatrices](https://webmatrices.com)
