mcp tweetbinder

This is a Model Context Protocol (MCP) server for the TweetBinder by Audiense API, allowing Claude and other MCP-compatible AI models to access TweetBinder by Audiense analytics data.

Features

• Access TweetBinder analytics directly from Claude
• Analyze hashtags, users, and conversations on Twitter/X
• Get engagement metrics, sentiment analysis, and more
• Create Twitter reports with custom search queries
• Check report generation status
• Retrieve detailed report statistics
• Get account balance and quota information
• Count tweets matching specific queries
• List and manage your TweetBinder reports
• Access tweet content and user information from reports

Installation

Installing via Smithery

To install mcp-tweetbinder for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @AudienseCo/mcp-tweetbinder --client claude

Manual Configuration

Prerequisites

• Node.js (v18 or higher)
• Claude Desktop App

• TweetBinder by Audiense account with API credentials

• Clone this repository

• Install dependencies:

  npm install

• Build the project:

  npm run build

You need a valid TweetBinder API Bearer Token to use this service. Set it in your environment:

export TWEETBINDER_API_TOKEN='your-bearer-token-here'

Usage with Claude Desktop

1. Edit your Claude Desktop configuration file:

2. MacOS:

   code ~/Library/Application Support/Claude/claude_desktop_config.json

3. Windows:

   code %AppData%Claudeclaude_desktop_config.json

4. Add this configuration:

"mcpServers": {
  "tweetbinder": {
    "command": "node",
    "args": [
      "/absolute/path/to/build/index.js"
    ],
    "env": {
      "TWEETBINDER_API_TOKEN": "your-bearer-token-here"
    }
  }
}

1. Restart Claude Desktop

Available Tools

create-twitter-report

Creates a new report that analyzes Twitter/X data based on a search query.

• Parameters:
• query (string): The search query for Twitter data. Can include operators like AND, OR, hashtags, mentions, etc.
• limit (number, optional): Maximum number of tweets to retrieve (up to 50,000).
• startDate (number, optional): Start date as Unix timestamp (seconds since epoch).
• endDate (number, optional): End date as Unix timestamp (seconds since epoch).

• reportType (enum, optional): Type of report to create: "7-day" for last week or "historical" for all time. Default: "7-day".

• Response:

• Report ID and status information for the created report.
• Instructions for checking report status and retrieving statistics.

create-twitter-count

Creates a new report that counts tweets matching a search query.

• Parameters:
• query (string): The search query for Twitter data. Can include operators like AND, OR, hashtags, mentions, etc.

• reportType (enum, optional): Type of report to create: "7-day" for last week or "historical" for all time. Default: "7-day".

• Response:

• Raw JSON response containing:
  • status: The status of the report creation
  • resourceId: The ID of the created report
  • error/message: Any error or status messages

list-reports

Retrieves a list of all your TweetBinder reports with sorting capabilities.

• Parameters:

• order (string, optional): Sorting parameter in the format 'field|direction'. Example: 'createdAt|-1' for newest first, 'createdAt|1' for oldest first.

• Response:

• Raw JSON response containing an array of reports with details for each:
  • id: Report ID
  • name: Report name
  • status: Current status (Generated, Waiting, etc.)
  • createdAt: Creation timestamp
  • updatedAt: Last update timestamp
  • type: Report type
  • source: Report source
  • query: Original search query

get-report-content

Retrieves the actual tweets or users from a generated report with advanced filtering and pagination.

• Parameters:
• reportId (string): The ID of the report to retrieve content for.
• contentType (enum): The type of content to retrieve: 'tweets' for tweet data or 'users' for user data.
• page (number, optional): Page number for pagination. Starts at 1.
• perPage (number, optional): Number of items per page.
• sortBy (string, optional): Field to sort by (e.g., 'createdAt', 'counts.favorites').
• sortDirection (enum, optional): Sort direction: '1' for ascending, '-1' for descending.

• filter (string, optional): JSON string with filter criteria. Example: '{"counts.favorites":{"$gt":10}}'

• Response:

• Raw JSON response containing:
  • items: Array of tweet or user objects
  • pagination: Information about total items and pages

When requesting tweets, detailed information is returned, including: - Tweet ID, text, creation date, language - Author details (name, username, followers, etc.) - Engagement metrics (retweets, likes, replies, etc.) - Media content (hashtags, images, links) - Sentiment analysis

When requesting users, information includes: - User ID, name, username - Profile picture URL - Follower and following counts - Verification status - User value and other metrics

Note: Report must be in 'Generated' status to access content. Use the get-report-status tool to check if a report is ready.

Query Syntax Examples: - #apple: Tweets containing the hashtag #apple - apple lang:en: English tweets containing "apple" - (#apple OR #iphone) -#android: Tweets with #apple or #iphone but not #android - @apple: Tweets mentioning @apple - from:apple: Tweets posted by user "apple"

Note: After creating the count report, use the get-report-status tool to check when it's ready, then use get-report-stats to get the actual count.

get-report-status

Checks the current status of a TweetBinder report.

• Parameters:

• reportId (string): The ID of the report to check.

• Response:

• The current status of the report, which can be one of:
  • Generated: The report is complete and ready to use.
  • Waiting: The report is still being generated or waiting for tweets to be collected.
  • Outdated: The report is being updated with new data and will be available soon.
  • Deleted: The report has been deleted and is no longer available.
  • Archived: The report has been archived and may be deleted soon.
• An explanation of what the status means and what actions are available.

Note: You must first create a report using the create-twitter-report or create-twitter-count tool to get a report ID.

get-report-stats

Retrieves comprehensive statistics and analytics for a TweetBinder report.

• Parameters:

• reportId (string): The ID of the report to retrieve statistics for.

• Response:

• A formatted summary of the report statistics including:
  • Overview: Total tweets, date range, contributors, engagement, media, and links.
  • Engagement Metrics: Potential reach, impressions, retweets, and likes.
  • Sentiment Analysis: Overall sentiment score and interpretation.
  • Top Contributors: Most active users and their tweet counts.
  • Popular Content: Most retweeted posts.
  • Frequently Used Hashtags: Common hashtags used in the conversation.

Note: The report must have "Generated" status before statistics can be retrieved. Use the get-report-status tool to check if a report is ready.

get-account-balances

Retrieves information about your account's credit balance, usage, and remaining quota.

• Parameters:

• None

• Returns:

• Raw JSON response containing:
  • total: Total credits available
  • used: Credits used
  • available: Credits currently available
  • discount: Any applicable discount
  • remainingReports: Number of reports remaining
  • quota: Quota information including:
  • startedAt: Quota period start date
  • finishedAt: Quota period end date
  • remaining: Remaining quota
  • used: Used quota
  • total: Total quota
• Any error or status messages

Troubleshooting

Tools Not Appearing in Claude

1. Check Claude Desktop logs:

tail -f ~/Library/Logs/Claude/mcp*.log

Authentication Issues

• Double-check credentials.
• Ensure the refresh token is still valid.
• Verify that the required API scopes are enabled and that you have enough credits.

Viewing Logs

To check server logs:

For MacOS/Linux:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

For Windows:

Get-Content -Path "$env:AppDataClaudeLogsmcp*.log" -Wait -Tail 20

Security Considerations

• Keep API credentials secure – never expose them in public repositories.
• Use environment variables to manage sensitive data.

? License

This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.