Metadata-Version: 2.5
Name: socials-mcp
Version: 0.2.1
Summary: MCP server unifié pour X/Twitter et Reddit — tout-en-un, pas de CLI externe
Project-URL: Homepage, https://github.com/nyrhe/socials-mcp
Project-URL: Repository, https://github.com/nyrhe/socials-mcp
Project-URL: Issues, https://github.com/nyrhe/socials-mcp/issues
Author: nyrhe
License: MIT
License-File: LICENSE
Keywords: mcp,reddit,socials,twitter,x
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: browser-cookie3>=0.19
Requires-Dist: click>=8.0
Requires-Dist: curl-cffi>=0.7
Requires-Dist: httpx
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: xclienttransaction>=1.0.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# socials-mcp

Unified MCP server for **X/Twitter** and **Reddit**.

> **MCP name:** `socials` — one server, two platforms.

## Install

```bash
uv tool install socials-mcp
```

## Login (optional)

1. Install [Cookie Editor](https://cookie-editor.com/) extension in your browser.

2. Go to [x.com](https://x.com) or [reddit.com](https://reddit.com) → open [Cookie Editor](https://cookie-editor.com/) → Export → Export as JSON (clipboard).

3. Run:

   ```bash
   socials-mcp x login
   # or
   socials-mcp reddit login
   ```

4. Paste the JSON (Ctrl+D to finish).

5. Enjoy!


## Config

```json
{
  "mcpServers": {
    "socials": {
      "command": "socials-mcp"
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `reddit_search` | Search Reddit (+ lightweight: fields, text_only, filters) |
| `reddit_read` | Read post + comments |
| `reddit_sub` | Browse subreddit (+ lightweight: fields, text_only, filters) |
| `reddit_sub_info` | Subreddit info |
| `reddit_user` | User profile |
| `reddit_user_posts` | User posts |
| `reddit_user_comments` | User comments |
| `reddit_popular` | Popular posts (/r/popular) |
| `reddit_popular_all` | Browse r/all |
| `reddit_feed` | Home feed (requires login) |
| `reddit_saved` | Saved posts (requires login) |
| `reddit_upvoted` | Upvoted posts (requires login) |
| `reddit_whoami` | Current account (requires login) |
| `reddit_status` | Auth status (requires login) |
| `reddit_comment` | Post a comment (requires login) |
| `reddit_create_post` | Create a self or link post (requires login) |
| `reddit_delete` | Delete a post or comment (requires login) |
| `reddit_save` | Save a post (requires login) |
| `reddit_unsave` | Unsave a post (requires login) |
| `reddit_upvote` | Upvote a post (requires login) |
| `reddit_subscribe` | Subscribe to subreddit (requires login) |
| `reddit_unsubscribe` | Unsubscribe from subreddit (requires login) |
| `reddit_subscriptions` | List subscribed subreddits (requires login) |
| `x_user` | User profile |
| `x_tweet` | Tweet + replies |
| `x_user_posts` | User tweets |
| `x_article` | Fetch Article |
| `x_search` | Search tweets (+ lightweight: fields, text_only, summarize, filters) |
| `x_feed` | Home timeline (+ lightweight: fields, text_only, filters) |
| `x_following_feed` | Following timeline (+ lightweight: fields, text_only, filters) |
| `x_bookmarks` | Bookmarks (requires login) |
| `x_whoami` | Current account (requires login) |
| `x_status` | Auth status (requires login) |
| `x_post` | Post a tweet (requires login) |
| `x_follow` | Follow user (requires login) |
| `x_unfollow` | Unfollow user (requires login) |
| `x_followers` | List followers (requires login) |
| `x_following` | List following (requires login) |
| `x_like` | Like tweet (requires login) |
| `x_unlike` | Unlike tweet (requires login) |
| `x_likes` | Liked tweets (requires login) |
| `x_retweet` | Retweet (requires login) |
| `x_unretweet` | Undo retweet (requires login) |
| `x_reply` | Reply to tweet (requires login) |
| `x_thread` | Post a thread, optional images (requires login) |
| `x_quote` | Quote tweet (requires login) |
| `x_bookmark` | Bookmark tweet (requires login) |
| `x_unbookmark` | Remove bookmark (requires login) |
| `x_delete` | Delete tweet (requires login) |
| `x_list` | Fetch List tweets (requires login) |
| `socials_status` | Auth status X + Reddit |
| `reddit_login_help` | Login help Reddit |
| `x_login_help` | Login help X |

## Lightweight mode

The read tools (`x_search`, `x_feed`, `x_following_feed`, `reddit_search`, `reddit_sub`) accept options to lighten the output:

| Option | Description | Tools |
|--------|-------------|-------|
| `fields` | Keep only the requested fields (supports `a.b` nesting) | all five |
| `text_only` | Return only the texts, separated by `---` | all five |
| `summarize` | Add engagement stats (count, avg/median/max likes) | `x_search`, `reddit_search` |
| `min_likes` | Minimum likes | `x_search`, `x_feed`, `x_following_feed` |
| `min_retweets` / `min_views` | Minimum retweets / views | `x_search` |
| `verified_only` | Verified accounts only | `x_search` |
| `min_score` / `min_comments` | Minimum Reddit score / comments | `reddit_search`, `reddit_sub` |
| `keywords` | Keep only items containing these keywords | all five |
| `exclude_keywords` | Drop items containing these keywords | `x_search`, `reddit_search` |
| `nsfw` | Reddit NSFW/SFW filter | `reddit_search` |

### Examples

```python
# Lightweight search: only text + author
mcp__socials__x_search(query="wow forever stress test", fields=["text", "author.screenName"])

# Plain text for quick analysis
mcp__socials__x_search(query="wow forever", text_only=true, max=50)

# Filter + engagement stats
mcp__socials__x_search(query="wow forever", min_likes=10, summarize=true)

# Reddit: popular posts of a sub
mcp__socials__reddit_sub(subreddit="wowforever", min_score=100, fields=["title", "ups", "num_comments"])
```

## CLI (optional)

The package also installs two terminal clients, `x` and `reddit` (also
available as `socials-mcp x ...` / `socials-mcp reddit ...`). The MCP server
does not use them.

## License

MIT
