# social-mcp

An [MCP](https://modelcontextprotocol.io) server that gives LLM agents (Claude Desktop, Claude Code, Cursor, custom LangGraph agents, etc.) read-only access to **YouTube** and **Instagram** analytics.

Most social media APIs return raw counts. Raw counts can't answer "is this video doing well?", so the server also computes the numbers a content strategist would actually look at:

- **Engagement rate**: (likes + comments) / views on YouTube, / followers on Instagram
- **Performance vs. the channel's own median**: a 20k-view video is a hit on a channel with a 3k median and a flop on a 500k one
- **Outlier detection**: items at 2× the median or more
- **Format split**: Shorts vs. long-form, Reels vs. feed posts

## Tools

| Tool | What it does | YouTube quota |
|---|---|---|
| `youtube_channel_overview` | Subscribers, total views, upload count; accepts `@handle` or channel ID | 1 |
| `youtube_recent_uploads` | Latest uploads with stats, median views and outliers | 3 |
| `youtube_search_videos` | Search with ordering, date and region filters, stats included | ~101 |
| `youtube_video_details` | Stats, duration and tags for up to 50 IDs | 1 per 50 |
| `youtube_top_comments` | Top-level comments, for sentiment and content ideas | 1 |
| `instagram_account_overview` | Followers, following and post counts | — |
| `instagram_recent_media` | Recent posts, engagement, outliers, Reels vs. feed split | — |
| `instagram_hashtag_top_media` | Top posts for a hashtag (Instagram limits this to 30 hashtags per 7 days) | — |

All tools are annotated `readOnlyHint: true`. The server never posts, comments or edits anything.

There is also a **`content_audit` prompt** that walks the model through auditing a channel and proposing five data-backed video ideas.

## Setup

```bash
git clone https://github.com/nilaydatta1234/mcp-social-tools.git
cd mcp-social-tools
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env    # then fill in your keys
```

**YouTube:** create an API key in Google Cloud Console and enable *YouTube Data API v3*. The default quota is 10,000 units per day. Responses are cached for `CACHE_TTL_SECONDS` (default 300), so an agent that asks the same thing twice doesn't pay twice.

**Instagram:** needs an Instagram Business or Creator account linked to a Facebook Page, plus a long-lived token with `instagram_basic` and `pages_show_list` (and `instagram_manage_insights` if you extend it). `IG_USER_ID` is the Instagram business account ID, not the Page ID.

Either platform can be left unconfigured. Its tools will then return a clear "not configured" error instead of crashing the server.

## Using it

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "social": {
      "command": "/absolute/path/to/mcp-social-tools/.venv/bin/social-mcp",
      "env": { "YOUTUBE_API_KEY": "..." }
    }
  }
}
```

For Claude Code: `claude mcp add social -- /absolute/path/to/.venv/bin/social-mcp`

### MCP Inspector (for poking at tools by hand)

```bash
npx @modelcontextprotocol/inspector social-mcp
```

### Over HTTP

```bash
social-mcp --transport streamable-http
```

## Design notes

- **Structured output.** Tools return JSON objects, not prose, so the model can compare numbers across calls instead of re-parsing text.
- **Errors the model can act on.** Quota exhaustion, expired Instagram tokens, disabled comments and rate limits come back as specific messages instead of a raw 403, so the agent can explain or back off.
- **Quota awareness.** `search` costs 100× more than other calls, and the tool description says so; models do read tool descriptions. Video stats are fetched in batches of 50.
- **Hidden counts.** Creators can hide likes and subscriber counts. Those come back as `null` rather than `0`, so engagement rates aren't silently wrong.

## Development

```bash
pytest          # all HTTP is mocked with httpx.MockTransport, so no keys needed
ruff check .
```

Project layout:

```
src/social_mcp/
  server.py      MCP tool/prompt registration and entrypoint
  youtube.py     YouTube Data API v3 client
  instagram.py   Instagram Graph API client
  metrics.py     engagement, outlier and duration helpers (pure functions)
  cache.py       TTL cache for API responses
tests/
```

## Roadmap

- [ ] TikTok Research API tools
- [ ] YouTube Analytics API (watch time, retention) via OAuth for your own channel
- [ ] Instagram media insights (reach, saves, shares)
- [ ] Optional SQLite snapshotting to track growth over time

## License

MIT