API Docs/Guides/MCP Integration

Integration Guide

𝕏 Bookmarks MCP ServerBeta

The TweetsMash MCP server connects AI assistants such as Claude, ChatGPT, and Cursor to your 𝕏 (Twitter) bookmarks using the Model Context Protocol (MCP). Search, filter, and label your saved posts through natural language commands.

MCP access requires an active API token. Generate one from Settings → Developer API — then connect over the hosted server at https://mcp.tweetsmash.com/api/mcp?token=YOUR_TOKEN.

What is MCP?

The Model Context Protocol (MCP) is a standard that allows AI assistants to securely access external data and tools. Our TweetsMash MCP service provides AI tools with direct access to your bookmarks, enabling powerful automation and organization capabilities.

Natural Language

Ask your AI assistant to find and organize bookmarks using simple commands

Smart Search

AI-powered search through your bookmarks with semantic understanding

Auto Organization

Automatically categorize and label bookmarks based on content

Prerequisites

TweetsMash API Token

Generate an API token from your TweetsMash account settings

MCP-Compatible AI Assistant

Use any AI assistant that supports the Model Context Protocol (Claude, Gemini, etc.)

TweetsMash MCP Service

Install and configure the TweetsMash MCP service on your system

🚀 Getting Started

Step 1: Generate TweetsMash API Token

Visit your TweetsMash account and generate an API token:

Go to your TweetsMash dashboard
Navigate to Settings → Integrations → API
Click "Generate New Token"
Copy the generated token (you'll need this for the next step)

Step 2: Choose Your Setup Method

Set up the MCP service locally using STDIO transport.

STDIO Configuration:

claude_desktop_config.json

{
  "mcpServers": {
    "tweetsmash": {
      "command": "npx",
      "args": ["@tweetsmash/mcp"],
      "env": {
        "TWEETSMASH_TOKEN": "your-token-here"
      }
    }
  }
}

Config file locations:

Claude: ~/.claude/claude_desktop_config.json
Other clients: Check your client's documentation

Step 3: Test Your Connection

Once configured, test the connection by asking your AI assistant:

"Show me my recent bookmarks"
"Find bookmarks about technology"
"How many bookmarks do I have?"
"List my labels"

Available Tools

39 tools, grouped by what they do. Every tool works over MCP and (except product help) maps to the REST API below.

Bookmarks

list_bookmarks

List user's Twitter bookmarks with optional filtering and pagination. Supports filtering by read status, media type, author, tags, date ranges, and sorting options.

Parameters:

•limit (1-100): Number of bookmarks to retrieve
•is_unread_only: Filter to only unread bookmarks
•media_type: Filter by media type (thread, media, replies, notes, links)
•author: Filter by specific author username
•tag: Filter by specific tag
•posted_from/posted_to: Filter by tweet posting date range
•sort_by: Sort order for results

search_bookmarks

Search through a user's Twitter bookmarks using either keyword (text) search or semantic (meaning-based) search. Supports all list_bookmarks filters, full-text search via the q field, and semantic search via the vector_search_term field for natural language or topic-based queries.

Parameters:

•q (required): Keyword or text search query
•vector_search_term: Semantic search query for natural language
•All list_bookmarks filtering parameters

get_bookmark

Fetch one bookmark with FULL content — the X Article body, the unrolled thread, notes, and replies (choose with include=article,thread,notes,replies).

get_bookmark_count

Get the total count of user's bookmarks with optional filtering. Useful for understanding the size of bookmark collections before listing them.

Parameters:

•All filtering parameters from list_bookmarks (except limit, cursor, sort_by)

setup_vector_store

Initialize the vector store that powers semantic bookmark search. Run this once, or whenever semantic search reports the vector store is not set up. Indexing large bookmark collections may take a few minutes.

Parameters:

•None required

Organize

list_labels

List all user's labels with their usage counts. Useful for discovering existing labels before adding new ones or to understand the current labeling system.

Parameters:

•None required

add_labels_to_tweets

Add a label to a list of tweets. Can use an existing label by ID or create a new label by name. This is useful for organizing and categorizing tweets after searching or filtering.

Parameters:

•tweet_ids (required): Array of tweet IDs to add the label to
•label_id: ID of an existing label (get this from list_labels)
•label_name: Name of the label to create and add
•Note: Use either label_id OR label_name, not both

remove_labels_from_tweets

Remove a label from a list of tweets by label name. Useful for reorganizing or cleaning up your labeling system after searching or filtering.

Parameters:

•tweet_ids (required): Array of tweet IDs to remove the label from
•label_name (required): Name of the label to remove

tag_bookmarks_by_filter

Add a label to every bookmark matching a filter, in one call (no list-then-loop).

archive_bookmarks

Bulk archive / unarchive / delete / undelete / mark read / unread a list of bookmark ids (max 500). Confirm with the user before deleting.

archive_bookmarks_by_filter

Apply archive / unarchive / delete / undelete to every bookmark matching a filter. Confirm before deleting.

Smart Views

list_smart_views

List the user’s Smart Views (saved filtered views).

get_smart_view

Get one Smart View by slug (its filter, tabs/buckets, sort).

get_smart_view_bookmarks

List the bookmarks inside a Smart View, optionally scoped to one tab/bucket.

create_smart_view

Create a Smart View from a filter so the user can reuse it.

update_smart_view

Update a Smart View (name, filter, tabs, sort).

delete_smart_view

Delete a Smart View.

Share & export

create_share_link

Create a public, read-only share link (valid 7 days) for a set of bookmarks or everything matching a filter.

revoke_share_link

Revoke a share link by its token.

trigger_pdf_export

Start a PDF export (ids, a filter, or the whole library). The file appears in the Export Center.

trigger_csv_export

Start a CSV export. The file appears in the Export Center.

trigger_json_export

Start a JSON export. The file appears in the Export Center.

Digests

list_digest_preferences

List the user’s email-digest schedules (bookmarks + Smart View digests).

update_digest_preference

Update a digest schedule (enable/pause, frequency, time).

delete_digest_preference

Remove a digest schedule.

list_past_digests

List past digests sent to the user’s email, newest first.

Twitter Lists

list_twitter_lists

List the X lists the user follows in Tweetsmash.

get_list_tweets

Get recent (LATEST) or top/trending (POPULARITY) tweets for a followed list — high-signal discovery to save from.

get_list_digests

List past Twitter-list email digests.

send_list_digest

Build and email a digest of a list’s high-signal tweets now.

Sync

get_sync_status

Notion / Google Sheets / Zotero: connected/enabled, synced vs pending counts, and errors.

get_bookmark_sync_status

Whether a specific bookmark has synced to a given connection.

Connection

get_connection_status

Whether the user’s tweets can be pulled: X (Twitter) API connection state, whether the browser extension synced recently, and a rolled-up can_pull + how.

fetch_recent_bookmarks

Force a server-side pull of the most recent bookmarks from the X API (needs a connected X account; extension-only accounts sync from the web app).

Account & memory

get_me

The current user’s account: identity, current plan and status, and usage (e.g. AI chat credits).

remember

Store a durable preference / fact / instruction for future sessions. Never store secrets.

recall

Retrieve durable memories, optionally filtered by a query.

forget

Delete a durable memory by key.

Product help

search_docs

Answer questions about Tweetsmash itself — features, how-to, pricing, plans, limits — from the built-in product guide.

API Endpoints Reference

The MCP tools internally use these TweetsMash API endpoints. You can also use them directly in your applications:

GET/v1/bookmarks

Retrieve bookmarks with filtering and pagination. Used by the list_bookmarks and search_bookmarks tools.

GET/v1/labels

Get all user labels. Used by the list_labels tool.

POST/v1/labels/add

Add labels to tweets. Used by the add_labels_to_tweets tool.

Supported AI Clients

Claude Desktop

Official Claude desktop application with MCP support. Documentation

Config: ~/.claude/claude_desktop_config.json

Raycast

Raycast AI with MCP integration.

Config: Raycast documentation

Other MCP Clients

Any AI assistant that supports the Model Context Protocol.

Check your client's documentation for MCP setup

Frequently Asked Questions

How does the AI assistant access my bookmarks?

The AI assistant connects to your TweetsMash account through the MCP protocol using your API token. Your data remains secure and is only accessed when you make specific requests.

Can I customize the AI assistant's behavior?

Yes! You can provide specific instructions to the AI assistant about how you want it to organize, categorize, or present your bookmarks. The AI learns from your preferences over time.

Is my data secure?

Absolutely. Your API token is encrypted and the AI assistant only accesses your bookmarks when you explicitly request it. No data is stored or shared with third parties.

What's the difference between Smithery and manual setup?

Smithery provides a managed, hosted solution with automatic updates and zero maintenance. Manual setup gives you full control but requires you to manage the server yourself.

Additional Resources

MCP Documentation

Smithery TweetsMash Server

MCP Service Source Code

API Docs/Guides/MCP Integration

Integration Guide

𝕏 Bookmarks MCP ServerBeta

MCP access requires an active API token. Generate one from Settings → Developer API — then connect over the hosted server at https://mcp.tweetsmash.com/api/mcp?token=YOUR_TOKEN.

What is MCP?

Natural Language

Ask your AI assistant to find and organize bookmarks using simple commands

Smart Search

AI-powered search through your bookmarks with semantic understanding

Auto Organization

Automatically categorize and label bookmarks based on content

Prerequisites

TweetsMash API Token

Generate an API token from your TweetsMash account settings

MCP-Compatible AI Assistant

Use any AI assistant that supports the Model Context Protocol (Claude, Gemini, etc.)

TweetsMash MCP Service

Install and configure the TweetsMash MCP service on your system

🚀 Getting Started

Step 1: Generate TweetsMash API Token

Visit your TweetsMash account and generate an API token:

Go to your TweetsMash dashboard
Navigate to Settings → Integrations → API
Click "Generate New Token"
Copy the generated token (you'll need this for the next step)

Step 2: Choose Your Setup Method

Set up the MCP service locally using STDIO transport.

STDIO Configuration:

claude_desktop_config.json

{
  "mcpServers": {
    "tweetsmash": {
      "command": "npx",
      "args": ["@tweetsmash/mcp"],
      "env": {
        "TWEETSMASH_TOKEN": "your-token-here"
      }
    }
  }
}

Config file locations:

Claude: ~/.claude/claude_desktop_config.json
Other clients: Check your client's documentation

Step 3: Test Your Connection

Once configured, test the connection by asking your AI assistant:

"Show me my recent bookmarks"
"Find bookmarks about technology"
"How many bookmarks do I have?"
"List my labels"

Available Tools

39 tools, grouped by what they do. Every tool works over MCP and (except product help) maps to the REST API below.

Bookmarks

list_bookmarks

List user's Twitter bookmarks with optional filtering and pagination. Supports filtering by read status, media type, author, tags, date ranges, and sorting options.

Parameters:

•limit (1-100): Number of bookmarks to retrieve
•is_unread_only: Filter to only unread bookmarks
•media_type: Filter by media type (thread, media, replies, notes, links)
•author: Filter by specific author username
•tag: Filter by specific tag
•posted_from/posted_to: Filter by tweet posting date range
•sort_by: Sort order for results

search_bookmarks

Parameters:

•q (required): Keyword or text search query
•vector_search_term: Semantic search query for natural language
•All list_bookmarks filtering parameters

get_bookmark

Fetch one bookmark with FULL content — the X Article body, the unrolled thread, notes, and replies (choose with include=article,thread,notes,replies).

get_bookmark_count

Get the total count of user's bookmarks with optional filtering. Useful for understanding the size of bookmark collections before listing them.

Parameters:

•All filtering parameters from list_bookmarks (except limit, cursor, sort_by)

setup_vector_store

Parameters:

•None required

Organize

list_labels

List all user's labels with their usage counts. Useful for discovering existing labels before adding new ones or to understand the current labeling system.

Parameters:

•None required

add_labels_to_tweets

Add a label to a list of tweets. Can use an existing label by ID or create a new label by name. This is useful for organizing and categorizing tweets after searching or filtering.

Parameters:

•tweet_ids (required): Array of tweet IDs to add the label to
•label_id: ID of an existing label (get this from list_labels)
•label_name: Name of the label to create and add
•Note: Use either label_id OR label_name, not both

remove_labels_from_tweets

Remove a label from a list of tweets by label name. Useful for reorganizing or cleaning up your labeling system after searching or filtering.

Parameters:

•tweet_ids (required): Array of tweet IDs to remove the label from
•label_name (required): Name of the label to remove

tag_bookmarks_by_filter

Add a label to every bookmark matching a filter, in one call (no list-then-loop).

archive_bookmarks

Bulk archive / unarchive / delete / undelete / mark read / unread a list of bookmark ids (max 500). Confirm with the user before deleting.

archive_bookmarks_by_filter

Apply archive / unarchive / delete / undelete to every bookmark matching a filter. Confirm before deleting.

Smart Views

list_smart_views

List the user’s Smart Views (saved filtered views).

get_smart_view

Get one Smart View by slug (its filter, tabs/buckets, sort).

get_smart_view_bookmarks

List the bookmarks inside a Smart View, optionally scoped to one tab/bucket.

create_smart_view

Create a Smart View from a filter so the user can reuse it.

update_smart_view

Update a Smart View (name, filter, tabs, sort).

delete_smart_view

Delete a Smart View.

Share & export

create_share_link

Create a public, read-only share link (valid 7 days) for a set of bookmarks or everything matching a filter.

revoke_share_link

Revoke a share link by its token.

trigger_pdf_export

Start a PDF export (ids, a filter, or the whole library). The file appears in the Export Center.

trigger_csv_export

Start a CSV export. The file appears in the Export Center.

trigger_json_export

Start a JSON export. The file appears in the Export Center.

Digests

list_digest_preferences

List the user’s email-digest schedules (bookmarks + Smart View digests).

update_digest_preference

Update a digest schedule (enable/pause, frequency, time).

delete_digest_preference

Remove a digest schedule.

list_past_digests

List past digests sent to the user’s email, newest first.

Twitter Lists

list_twitter_lists

List the X lists the user follows in Tweetsmash.

get_list_tweets

Get recent (LATEST) or top/trending (POPULARITY) tweets for a followed list — high-signal discovery to save from.

get_list_digests

List past Twitter-list email digests.

send_list_digest

Build and email a digest of a list’s high-signal tweets now.

Sync

get_sync_status

Notion / Google Sheets / Zotero: connected/enabled, synced vs pending counts, and errors.

get_bookmark_sync_status

Whether a specific bookmark has synced to a given connection.

Connection

get_connection_status

Whether the user’s tweets can be pulled: X (Twitter) API connection state, whether the browser extension synced recently, and a rolled-up can_pull + how.

fetch_recent_bookmarks

Force a server-side pull of the most recent bookmarks from the X API (needs a connected X account; extension-only accounts sync from the web app).

Account & memory

get_me

The current user’s account: identity, current plan and status, and usage (e.g. AI chat credits).

remember

Store a durable preference / fact / instruction for future sessions. Never store secrets.

recall

Retrieve durable memories, optionally filtered by a query.

forget

Delete a durable memory by key.

Product help

search_docs

Answer questions about Tweetsmash itself — features, how-to, pricing, plans, limits — from the built-in product guide.

API Endpoints Reference

The MCP tools internally use these TweetsMash API endpoints. You can also use them directly in your applications:

GET/v1/bookmarks

Retrieve bookmarks with filtering and pagination. Used by the list_bookmarks and search_bookmarks tools.

GET/v1/labels

Get all user labels. Used by the list_labels tool.

POST/v1/labels/add

Add labels to tweets. Used by the add_labels_to_tweets tool.

Supported AI Clients

Claude Desktop

Official Claude desktop application with MCP support. Documentation

Config: ~/.claude/claude_desktop_config.json

Raycast

Raycast AI with MCP integration.

Config: Raycast documentation

Other MCP Clients

Any AI assistant that supports the Model Context Protocol.

Check your client's documentation for MCP setup

Frequently Asked Questions

How does the AI assistant access my bookmarks?

The AI assistant connects to your TweetsMash account through the MCP protocol using your API token. Your data remains secure and is only accessed when you make specific requests.

Can I customize the AI assistant's behavior?

Yes! You can provide specific instructions to the AI assistant about how you want it to organize, categorize, or present your bookmarks. The AI learns from your preferences over time.

Is my data secure?

Absolutely. Your API token is encrypted and the AI assistant only accesses your bookmarks when you explicitly request it. No data is stored or shared with third parties.

What's the difference between Smithery and manual setup?

Smithery provides a managed, hosted solution with automatic updates and zero maintenance. Manual setup gives you full control but requires you to manage the server yourself.

Additional Resources

MCP Documentation

Smithery TweetsMash Server

MCP Service Source Code