TweetBinder by Audiense MCP Server

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

Manual Configuration

Prerequisites

• **Node.js** (v18 or higher)

• **Claude Desktop App**

• **TweetBinder by Audiense** account with API credentials

1. Clone this repository

2. Install dependencies: ```bash npm install ```

3. Build the project: ```bash npm run build ```

Usage with Claude Desktop

1. Edit your Claude Desktop configuration file: - **MacOS:** ```bash code ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` - **Windows:** ```bash code %AppData%\Claude\claude_desktop_config.json ```

2. Add this configuration:

1. Restart Claude Desktop

Available Tools

`create-twitter-report`

• **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`

• **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`

• **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`

• **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

• `#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"

`get-report-status`

• **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.

`get-report-stats`

• **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.

`get-account-balances`

• **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:

1. Verify environment variables are set correctly.

2. Ensure the absolute path to index.js is correct.

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

For MacOS/Linux:

For Windows:

Security Considerations

• Keep API credentials secure never expose them in public repositories.

• Use environment variables to manage sensitive data.

License