<div align="center">

# maxsentiment

### An MCP server that tells you what people actually think about any social post.

**Paste a link. It reads every comment, finds the themes, and shows you which themes got the most engagement. Works on LinkedIn, Instagram, X, YouTube and Reddit.**

![Python](https://img.shields.io/badge/python-3.10+-3776ab?style=flat-square&logo=python&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-server-5c4ee5?style=flat-square)
![Platforms](https://img.shields.io/badge/platforms-5-7f8c5c?style=flat-square)
![License](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)

[What it does](#what-it-does) · [Examples](#examples) · [Platforms](#platforms) · [Quick start](#quick-start) · [FAQ](#faq)

</div>

> [!IMPORTANT]
> maxsentiment reads **public posts** using **your own logged-in session**. It never logs
> in for you, posts, or makes accounts. It just reads the comments your browser can already
> see. YouTube needs no login at all.

---

## What it does

Reading a post's comments by hand is impossible once there are more than a few dozen. This
does it for you. Two things:

**1. It reads the engagement on a post.** Every comment and every reply. On any platform you
support: LinkedIn, Instagram, X, YouTube, Reddit. You paste a link, it pulls the lot.

**2. It makes sense of it.** It uses the OpenAI Decisions API to classify every comment, and
GPT-5 to work out the themes. Then it buckets the result by engagement:

> this theme got this much engagement. that theme got that much. ranked, top to bottom.

So instead of "412 comments," you get the real breakdown:

> 38% of the engagement was people asking for proof. 22% was price complaints. 15% was
> praise. 9% was "not for us."

That is the whole point. What the conversation was actually about, and which parts of it
people actually cared about. (A comment counts for more than a like, because writing takes
more effort than tapping. So the ranking reflects real attention, not drive-by taps.)

## Examples

Point it at a post and you get four things:

| | |
|---|---|
| 📊 **Engagement** | which themes pulled the most comments, replies and shares, ranked |
| 🎭 **Sentiment** | how people felt about each theme. for it, against it, or just asking |
| 👥 **Who's engaging** | the accounts showing up, the repeat voices, the verified names |
| 🧵 **The theme** | the one objection or idea that keeps coming back, even on different platforms |

**A real run. Kunal Shah's "WhatsApp" post on X, 360 replies:**

> The top of the raw feed was all promo spam (trading pitches, ads). maxsentiment drops that
> on its own, and the real chorus underneath is one clear theme: "WhatsApp has become a spam
> and ads machine." Under it: give us a separate business inbox, make the AI opt-in, fix the
> fraud and impersonation. Loudest single reply: "it no longer feels like a messenger." Not
> hostile. A clear, united ask, which is far more useful to know than a star rating.

> _Want the showcase filled in with specific posts (say the same Deepinder Goyal topic across
> LinkedIn and X, or a Kunal Kamra post across Instagram and X, to show one theme repeating on
> every channel)? Those are live runs. See [Quick start](#quick-start)._

## Platforms

| platform | paste a post link, get | login |
|---|---|---|
| LinkedIn | comments on the post | your cookies |
| Instagram | comments on the post | your cookies |
| X / Twitter | replies on the tweet | your cookies |
| YouTube | comments on the video | **none (public)** |
| Reddit | the whole thread | your cookies |

Every platform reads the same internal web API your browser uses. Nothing is logged in, made,
or evaded. You export your session cookies once, with a browser extension. YouTube needs
nothing.

## Quick start

```bash
pip install -r requirements.txt
```

Register the MCP server with your agent (Claude Code or Desktop). Command `python`, args
`["server.py"]`, env `{ "OPENAI_API_KEY": "sk-..." }`. Then just talk to it:

```text
What are people saying on https://x.com/user/status/123456?
Which themes got the most engagement, and how did people feel?
```

The agent walks you through exporting cookies (it points you at the open-source "Get
cookies.txt LOCALLY" extension), reads the post, and reports back. The skill in
`skills/maxsentiment/` teaches it the whole workflow.

**The two calls it runs under the hood:**

```text
ms_post(url)         pull every comment on the post
ms_build_tree(...)   group them by theme, ranked by engagement
```

## How it's built

- **Platform clients** read each site's own internal web API with your session cookies.
- **The OpenAI Decisions API** classifies every comment. Fast, deterministic, cheap: a few
  thousand comments costs under a dollar. **GPT-5** names and groups the themes.
- **A spam filter runs first**, so promo, ads and giveaways never pollute the ranking.

## FAQ

<details>
<summary><strong>Does this log into my accounts or post anything?</strong></summary>

No. It never logs in, posts, likes, follows, or makes accounts. It reads public comments
using a session cookie you exported yourself. It only reads.
</details>

<details>
<summary><strong>Where do my cookies live?</strong></summary>

In `~/.maxsentiment/`, outside any repo, one file per platform. They're never committed and
never sent anywhere except the platform they belong to. Scraped comments write to
`maxsentiment_runs/`, which is `.gitignore`d.
</details>

<details>
<summary><strong>What does it cost to run?</strong></summary>

Scraping is free. The theme analysis uses the OpenAI Decisions API, where input is cheap and
output is free, so a run over a few thousand comments is well under a dollar. The key is read
from `OPENAI_API_KEY`.
</details>

<details>
<summary><strong>Which agents can use it?</strong></summary>

Any agent that supports a local MCP server (Claude Code, Claude Desktop, and others). Or use
the Python library directly.
</details>

<details>
<summary><strong>Why is LinkedIn different?</strong></summary>

LinkedIn serves its comments as a heavier server-driven page, not a clean data feed, so it
needs a fully fresh session. Same input and output as the others, just more machinery behind
it.
</details>

## Privacy

Sessions live in `~/.maxsentiment/`, outside any repo, so cookies never get committed.
Scraped comments write to `maxsentiment_runs/`, which is `.gitignore`d. This repo is the tool.
Whatever you point it at stays on your machine.

## Not for

Making fake accounts, scraping strangers at scale, evading blocks, or building a dossier on a
private person. It drives your own session against public posts. Keep it there.

## License

[MIT](LICENSE).