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

Node.js (v16 or later)
A Syften account with API access
Claude Desktop app or VSCode with Claude extension

Installation

Clone the repository:

git clone https://github.com/fred-em/social-listening.git
cd social-listening

Install dependencies:

npm install

Build the server:

npm run build

Configuration

1. Syften API Setup

Log in to your Syften account
Go to Settings > API Access
Generate an API key if you haven't already
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:

{
  "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:

{
  "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.

{
  "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.

{
  "endpoint_url": "https://your-webhook.com/endpoint",
  "secret_token": "your-secret-token",
  "enabled": true
}

3. backfill_month

Backfill mentions for a specific month.

{
  "year": 2024,
  "month": 2
}

4. sync_latest

Sync new mentions since last update.

{}

5. analyze_trends

Analyze mention trends over time.

{
  "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.

{
  "start_date": "2024-01-01",
  "end_date": "2024-02-01",
  "limit": 10
}

7. nlp_prompt

Process natural language queries.

{
  "prompt": "show me feedback mentions from last week"
}

8. get_ai_filtered_mentions

Get mentions processed by AI filtering.

{
  "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:

Configure AI filtering:

Configure the social listening AI filter to detect bug reports and feature requests with 80% confidence.

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".

Analyze trends:

Show me the trend of bug reports and feature requests from last month.

Get filtered mentions:

Show me all high-confidence bug reports from the past week.

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:

{
  "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

# Install dependencies
npm install

# Build the server
npm run build

# Run tests
npm test

Adding new features

Implement new functionality in src/
Add tests in tests/
Build and test locally
Submit a pull request

Troubleshooting

Webhook errors: Ensure your webhook endpoint is accessible and supports HTTPS
API key issues: Verify your Syften API key is correctly set in the configuration
Database errors: Check if the data directory exists and is writable

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

MIT License - see LICENSE file for details