@tweetsmash/mcp

Tweetsmash MCP Service

A Model Context Protocol (MCP) service that provides AI assistants with access to Tweetsmash bookmark management capabilities.

Overview

This MCP service allows AI assistants to:

• List user's Twitter bookmarks with filtering and pagination
• Search through bookmarks using text queries
• Get bookmark counts with various filters
• Filter by read status, media type, author, tags, and date ranges
• List all user labels with usage counts
• Add labels to tweets for organization and categorization

Setup

Prerequisites

• Node.js 18+
• A valid Tweetsmash API token

Environment Variables

Create a .env file in the mcp-service directory:

TWEETSMASH_TOKEN=your_tweetsmash_api_token_here
NODE_ENV=development

Installation

# Install dependencies
npm install

# Run the service
npm start

# For development with auto-restart
npm run dev

Docker Setup

# Build and run with docker-compose
docker-compose up mcp-service

# For development mode
docker-compose --profile dev up mcp-service-dev

Available Tools

1. list_bookmarks

Lists user's Twitter bookmarks with optional filtering and pagination.

Parameters:

• limit (number, 1-100): Number of bookmarks to retrieve
• cursor (string): Pagination cursor for next page
• is_unread_only (boolean): Filter to only unread bookmarks
• hide_archived (boolean): Hide archived bookmarks
• media_type (enum): Filter by media type (thread, media, replies, notes, links)
• author (string): Filter by author username
• tag (string): Filter by tag
• posted_from/posted_to (string): Filter by tweet posting date range
• bookmarked_from/bookmarked_to (string): Filter by bookmark date range
• sort_by (enum): Sort order for results

2. search_bookmarks

Searches through bookmarks using a text query.

Parameters:

• q (string, required): Search query
• All the same filtering parameters as list_bookmarks

3. get_bookmark_count

Gets the total count of bookmarks with optional filtering.

Parameters:

• All filtering parameters except limit, cursor, and sort_by

4. list_labels

Lists all user's labels with their usage counts.

Parameters:

• None required

5. add_labels_to_tweets

Adds a label to a list of tweets. Can use existing label by ID or create new label by name.

Parameters:

• tweet_ids (array, required): Array of tweet IDs to label
• label_id (string): ID of existing label (use with list_labels)
• label_name (string): Name of new label to create
• Note: Either label_id or label_name must be provided

API Integration

The service integrates with the Tweetsmash API at https://api.tweetsmash.com/v1/bookmarks using Bearer token authentication.

Error Handling

The service includes comprehensive error handling and validation:

• Invalid API tokens return authentication errors
• Malformed requests are validated using Zod schemas
• API errors are properly formatted and returned to the client

Development

The service is built using:

• @modelcontextprotocol/sdk for MCP protocol implementation
• Zod for request/response validation
• Standard Node.js fetch for API calls

Usage with AI Assistants

This MCP service can be integrated with AI assistants that support the Model Context Protocol, allowing them to access and manage Tweetsmash bookmarks on behalf of users.