Social Listening MCP Server
by fred-em
# Social Listening MCP Server
A Model Context Protocol (MCP) server that provides social listening capabilities through Syften's API. This server enables AI-powered analysis of social mentions, with support for real-time notifications via webhooks.
## Features
- Real-time social mention monitoring
- AI-powered content categorization
- Webhook notifications for important mentions
- Historical data backfilling
- Trend analysis and reporting
- Natural language query support
## Prerequisites
1. Node.js (v16 or later)
2. A Syften account with API access
3. Claude Desktop app or VSCode with Claude extension
## Installation
1. Clone the repository:
```bash
git clone https://github.com/fred-em/social-listening.git
cd social-listening
```
2. Install dependencies:
```bash
npm install
```
3. Build the server:
```bash
npm run build
```
## Configuration
### 1. Syften API Setup
1. Log in to your Syften account
2. Go to Settings > API Access
3. Generate an API key if you haven't already
4. Copy your API key for the next step
### 2. Claude Desktop Configuration
Add the server configuration to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"social-listening": {
"command": "node",
"args": ["/absolute/path/to/social-listening/build/index.js"],
"env": {
"SYFTEN_API_KEY": "your-api-key-here"
}
}
}
}
```
### 3. VSCode Configuration (Optional)
If you're using VSCode with the Claude extension, add the configuration to `/Users/YOUR_USERNAME/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:
```json
{
"mcpServers": {
"social-listening": {
"command": "node",
"args": ["/absolute/path/to/social-listening/build/index.js"],
"env": {
"SYFTEN_API_KEY": "your-api-key-here"
}
}
}
}
```
## Available Tools
### 1. configure_ai_filter
Configure AI filtering settings for mention analysis.
```json
{
"enabled": true,
"min_confidence": 0.7,
"categories": ["spam", "support", "feedback", "bug_report", "feature_request"],
"webhook_url": "https://your-webhook.com/endpoint",
"webhook_secret": "your-secret-token"
}
```
### 2. setup_webhook
Configure webhook endpoint for real-time notifications.
```json
{
"endpoint_url": "https://your-webhook.com/endpoint",
"secret_token": "your-secret-token",
"enabled": true
}
```
### 3. backfill_month
Backfill mentions for a specific month.
```json
{
"year": 2024,
"month": 2
}
```
### 4. sync_latest
Sync new mentions since last update.
```json
{}
```
### 5. analyze_trends
Analyze mention trends over time.
```json
{
"start_date": "2024-01-01",
"end_date": "2024-02-01",
"group_by": "day",
"tags": ["feature", "bug"]
}
```
### 6. get_top_sources
Get top mention sources/authors.
```json
{
"start_date": "2024-01-01",
"end_date": "2024-02-01",
"limit": 10
}
```
### 7. nlp_prompt
Process natural language queries.
```json
{
"prompt": "show me feedback mentions from last week"
}
```
### 8. get_ai_filtered_mentions
Get mentions processed by AI filtering.
```json
{
"start_date": "2024-01-01",
"end_date": "2024-02-01",
"min_confidence": 0.8,
"categories": ["feedback", "bug_report"],
"limit": 50
}
```
## Example Usage in Claude
Here are some example prompts you can use with Claude:
1. Configure AI filtering:
```
Configure the social listening AI filter to detect bug reports and feature requests with 80% confidence.
```
2. Set up webhook notifications:
```
Set up a webhook for the social listening server to send notifications to https://my-server.com/webhook with the secret token "my-secret".
```
3. Analyze trends:
```
Show me the trend of bug reports and feature requests from last month.
```
4. Get filtered mentions:
```
Show me all high-confidence bug reports from the past week.
```
5. Natural language queries:
```
What kind of feedback have we received about the new feature launch?
```
## Webhook Integration
When configuring webhooks, the server will send notifications in this format:
```json
{
"mention_url": "https://example.com/post",
"ai_score": 0.95,
"ai_categories": ["bug_report", "feature_request"],
"timestamp": "2024-02-12T15:30:00Z"
}
```
Headers included with webhook requests:
- `Content-Type: application/json`
- `X-Webhook-Secret: your-secret-token`
## Development
### Building from source
```bash
# Install dependencies
npm install
# Build the server
npm run build
# Run tests
npm test
```
### Adding new features
1. Implement new functionality in `src/`
2. Add tests in `tests/`
3. Build and test locally
4. Submit a pull request
## Troubleshooting
1. **Webhook errors**: Ensure your webhook endpoint is accessible and supports HTTPS
2. **API key issues**: Verify your Syften API key is correctly set in the configuration
3. **Database errors**: Check if the `data` directory exists and is writable
## Contributing
1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request
## License
MIT License - see LICENSE file for details