# sprout-mcp

An MCP (Model Context Protocol) server that wraps the [Sprout Social Public API](https://developers.sproutsocial.com/), letting Claude and other MCP clients interact with your Sprout Social account directly.

## Tools

### Metadata
| Tool | Description |
|---|---|
| `list_customers` | List all customers/accounts accessible with your API token |
| `list_profiles` | List all social profiles for a customer |
| `list_tags` | List all message tags |
| `list_groups` | List all profile groups |
| `list_users` | List all active users |
| `list_teams` | List all teams |

### Analytics
| Tool | Description |
|---|---|
| `get_profile_analytics` | Get aggregated metrics by profile (impressions, engagements, follower growth, etc.) |
| `get_post_analytics` | Get metrics for individual published posts — also use this for post counts |

### Listening
| Tool | Description |
|---|---|
| `list_listening_topics` | List all Listening topics and their IDs |
| `get_listening_messages` | Fetch messages from a Listening topic, filterable by network (Reddit, Twitter, etc.) |

### Smart Inbox
| Tool | Description |
|---|---|
| `get_messages` | Retrieve inbound inbox messages (mentions, DMs, comments) |

### Publishing
| Tool | Description |
|---|---|
| `list_publishing_posts` | List published, scheduled, or draft posts |
| `create_post` | Create a draft or scheduled post |
| `get_publishing_post` | Retrieve a specific post by ID |

> **Note:** All tools return structured JSON error details on failure (HTTP status, endpoint, and API error body) instead of raw exceptions.

## Setup

### Prerequisites
- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- A Sprout Social account with API access

### Install

```bash
git clone https://github.com/jmeserve/sprout-mcp.git
cd sprout-mcp
uv sync
```

### Configure

Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
```

```env
SPROUT_API_TOKEN=your_api_token_here
SPROUT_CUSTOMER_ID=your_customer_id_here
```

- **SPROUT_API_TOKEN** — Generate at Sprout Social → Settings → API → OAuth tokens
- **SPROUT_CUSTOMER_ID** — Found in your Sprout Social account URL or via the `list_customers` tool

### Add to Claude Code

Add to your `~/.claude.json` MCP servers config:

```json
{
  "mcpServers": {
    "sprout-social": {
      "command": "uv",
      "args": ["--directory", "/path/to/sprout-mcp", "run", "sprout-mcp"],
      "env": {
        "SPROUT_API_TOKEN": "your_api_token_here",
        "SPROUT_CUSTOMER_ID": "your_customer_id_here"
      }
    }
  }
}
```

### Add to Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sprout-social": {
      "command": "uv",
      "args": ["--directory", "/path/to/sprout-mcp", "run", "sprout-mcp"],
      "env": {
        "SPROUT_API_TOKEN": "your_api_token_here",
        "SPROUT_CUSTOMER_ID": "your_customer_id_here"
      }
    }
  }
}
```

## Development

```bash
uv sync
uv run sprout-mcp       # run the server
uv run mcp dev sprout_mcp/server.py  # run with MCP inspector
```