MCP

Official7 toolsLive

by RamyaChinnadurai

Search, label, and manage your X (Twitter) bookmarks from any MCP client via Tweetsmash

Topics

ai-agentsbookmarksclaudemcpmcp-servermodel-context-protocoltwitterx

Captured live from the server via tools/list.

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. IMPORTANT: Use this tool (with the 'author' parameter) when the user asks to show tweets by a specific author.

Parameters13

is_unread_only	boolean	optional	Filter to only unread bookmarks
hide_archived	boolean	optional	Hide archived bookmarks
media_type	string	optional	Filter by media type
author	string	optional	Filter by author username. Use this parameter when the user wants to find tweets by a specific author (e.g., 'Show tweets by @user'). Do NOT use 'q' for author names.
tag	string	optional	Filter by tag
posted_from	string	optional	Filter tweets posted after this date (ISO 8601 string)
posted_to	string	optional	Filter tweets posted before this date (ISO 8601 string)
bookmarked_from	string	optional	Filter bookmarks added after this date (ISO 8601 string)
bookmarked_to	string	optional	Filter bookmarks added before this date (ISO 8601 string)
limit	number	optional	Number of bookmarks to retrieve (1-100)
cursor	string	optional	Pagination cursor for next page
sort_by	string	optional	Sort order for results
sort_cursor	string	optional	Cursor for pagination when using sort_by (use value from meta.sort_cursor of previous response)

Raw schema

{
  "type": "object",
  "properties": {
    "is_unread_only": {
      "type": "boolean",
      "description": "Filter to only unread bookmarks"
    },
    "hide_archived": {
      "type": "boolean",
      "description": "Hide archived bookmarks"
    },
    "media_type": {
      "type": "string",
      "enum": [
        "thread",
        "media",
        "replies",
        "notes",
        "links"
      ],
      "description": "Filter by media type"
    },
    "author": {
      "type": "string",
      "description": "Filter by author username. Use this parameter when the user wants to find tweets by a specific author (e.g., 'Show tweets by @user'). Do NOT use 'q' for author names."
    },
    "tag": {
      "type": "string",
      "description": "Filter by tag"
    },
    "posted_from": {
      "type": "string",
      "description": "Filter tweets posted after this date (ISO 8601 string)"
    },
    "posted_to": {
      "type": "string",
      "description": "Filter tweets posted before this date (ISO 8601 string)"
    },
    "bookmarked_from": {
      "type": "string",
      "description": "Filter bookmarks added after this date (ISO 8601 string)"
    },
    "bookmarked_to": {
      "type": "string",
      "description": "Filter bookmarks added before this date (ISO 8601 string)"
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Number of bookmarks to retrieve (1-100)"
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor for next page"
    },
    "sort_by": {
      "type": "string",
      "enum": [
        "POSTED_DATE_ASC",
        "POSTED_DATE_DESC",
        "OLDEST_FIRST",
        "NEWEST_FIRST"
      ],
      "default": "NEWEST_FIRST",
      "description": "Sort order for results"
    },
    "sort_cursor": {
      "type": "string",
      "description": "Cursor for pagination when using sort_by (use value from meta.sort_cursor of previous response)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_bookmarks

Search through a user's Twitter bookmarks using keyword search (q), semantic search (vector_search_term), or author filtering (author). At least one of q, vector_search_term, or author should be provided. IMPORTANT: Use the 'author' parameter for filtering by author, not the 'q' field.

Parameters15

is_unread_only	boolean	optional	Filter to only unread bookmarks
hide_archived	boolean	optional	Hide archived bookmarks
media_type	string	optional	Filter by media type
author	string	optional	Filter by author username. Use this parameter when the user wants to find tweets by a specific author (e.g., 'Show tweets by @user'). Do NOT use 'q' for author names.
tag	string	optional	Filter by tag
posted_from	string	optional	Filter tweets posted after this date (ISO 8601 string)
posted_to	string	optional	Filter tweets posted before this date (ISO 8601 string)
bookmarked_from	string	optional	Filter bookmarks added after this date (ISO 8601 string)
bookmarked_to	string	optional	Filter bookmarks added before this date (ISO 8601 string)
q	string	optional	Keyword or text search query for finding bookmarks by exact words or phrases in tweet content. Do NOT use this for author names - use the 'author' parameter instead.
vector_search_term	string	optional	Semantic search query for retrieving bookmarks based on meaning and context, not just keywords. Use for natural language questions or topic-based searches.
limit	number	optional	Number of bookmarks to retrieve (1-100)
cursor	string	optional	Pagination cursor for next page
sort_by	string	optional	Sort order for results
sort_cursor	string	optional	Cursor for pagination when using sort_by (use value from meta.sort_cursor of previous response)

Raw schema

{
  "type": "object",
  "properties": {
    "is_unread_only": {
      "type": "boolean",
      "description": "Filter to only unread bookmarks"
    },
    "hide_archived": {
      "type": "boolean",
      "description": "Hide archived bookmarks"
    },
    "media_type": {
      "type": "string",
      "enum": [
        "thread",
        "media",
        "replies",
        "notes",
        "links"
      ],
      "description": "Filter by media type"
    },
    "author": {
      "type": "string",
      "description": "Filter by author username. Use this parameter when the user wants to find tweets by a specific author (e.g., 'Show tweets by @user'). Do NOT use 'q' for author names."
    },
    "tag": {
      "type": "string",
      "description": "Filter by tag"
    },
    "posted_from": {
      "type": "string",
      "description": "Filter tweets posted after this date (ISO 8601 string)"
    },
    "posted_to": {
      "type": "string",
      "description": "Filter tweets posted before this date (ISO 8601 string)"
    },
    "bookmarked_from": {
      "type": "string",
      "description": "Filter bookmarks added after this date (ISO 8601 string)"
    },
    "bookmarked_to": {
      "type": "string",
      "description": "Filter bookmarks added before this date (ISO 8601 string)"
    },
    "q": {
      "type": "string",
      "minLength": 1,
      "description": "Keyword or text search query for finding bookmarks by exact words or phrases in tweet content. Do NOT use this for author names - use the 'author' parameter instead."
    },
    "vector_search_term": {
      "type": "string",
      "minLength": 1,
      "description": "Semantic search query for retrieving bookmarks based on meaning and context, not just keywords. Use for natural language questions or topic-based searches."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Number of bookmarks to retrieve (1-100)"
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor for next page"
    },
    "sort_by": {
      "type": "string",
      "enum": [
        "POSTED_DATE_ASC",
        "POSTED_DATE_DESC",
        "OLDEST_FIRST",
        "NEWEST_FIRST"
      ],
      "default": "NEWEST_FIRST",
      "description": "Sort order for results"
    },
    "sort_cursor": {
      "type": "string",
      "description": "Cursor for pagination when using sort_by (use value from meta.sort_cursor of previous response)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters9

is_unread_only	boolean	optional	Filter to only unread bookmarks
hide_archived	boolean	optional	Hide archived bookmarks
media_type	string	optional	Filter by media type
author	string	optional	Filter by author username. Use this parameter when the user wants to find tweets by a specific author (e.g., 'Show tweets by @user'). Do NOT use 'q' for author names.
tag	string	optional	Filter by tag
posted_from	string	optional	Filter tweets posted after this date (ISO 8601 string)
posted_to	string	optional	Filter tweets posted before this date (ISO 8601 string)
bookmarked_from	string	optional	Filter bookmarks added after this date (ISO 8601 string)
bookmarked_to	string	optional	Filter bookmarks added before this date (ISO 8601 string)

Raw schema

{
  "type": "object",
  "properties": {
    "is_unread_only": {
      "type": "boolean",
      "description": "Filter to only unread bookmarks"
    },
    "hide_archived": {
      "type": "boolean",
      "description": "Hide archived bookmarks"
    },
    "media_type": {
      "type": "string",
      "enum": [
        "thread",
        "media",
        "replies",
        "notes",
        "links"
      ],
      "description": "Filter by media type"
    },
    "author": {
      "type": "string",
      "description": "Filter by author username. Use this parameter when the user wants to find tweets by a specific author (e.g., 'Show tweets by @user'). Do NOT use 'q' for author names."
    },
    "tag": {
      "type": "string",
      "description": "Filter by tag"
    },
    "posted_from": {
      "type": "string",
      "description": "Filter tweets posted after this date (ISO 8601 string)"
    },
    "posted_to": {
      "type": "string",
      "description": "Filter tweets posted before this date (ISO 8601 string)"
    },
    "bookmarked_from": {
      "type": "string",
      "description": "Filter bookmarks added after this date (ISO 8601 string)"
    },
    "bookmarked_to": {
      "type": "string",
      "description": "Filter bookmarks added before this date (ISO 8601 string)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_labels

List all user's labels with their usage counts. Useful for discovering existing labels before adding new ones.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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. Either label_id or label_name must be provided.

Parameters3

tweet_ids	array	required	Array of tweet IDs to add the label to
label_id	string	optional	ID of existing label (use either label_id or label_name)
label_name	string	optional	Name of the label to create/add (use either label_id or label_name)

Raw schema

{
  "type": "object",
  "properties": {
    "tweet_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "Array of tweet IDs to add the label to"
    },
    "label_id": {
      "type": "string",
      "description": "ID of existing label (use either label_id or label_name)"
    },
    "label_name": {
      "type": "string",
      "description": "Name of the label to create/add (use either label_id or label_name)"
    }
  },
  "required": [
    "tweet_ids"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

remove_labels_from_tweets

Remove a label from a list of tweets using label_name.

Parameters2

tweet_ids	array	required	Array of tweet IDs to remove label from
label_name	string	required	Name of the label to remove

Raw schema

{
  "type": "object",
  "properties": {
    "tweet_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "Array of tweet IDs to remove label from"
    },
    "label_name": {
      "type": "string",
      "minLength": 1,
      "description": "Name of the label to remove"
    }
  },
  "required": [
    "tweet_ids",
    "label_name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

setup_vector_store

Initialize the vector store for semantic bookmark search. CRITICAL: When vector/semantic search fails with 'Vector Store Not Setup' error, call this tool. This is an async operation that may take a few minutes for large bookmark collections.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md2 KBView on GitHub

Tweetsmash MCP Server: X (Twitter) Bookmarks for AI Agents

The Tweetsmash MCP server connects Claude, ChatGPT, Cursor, Raycast, and any Model Context Protocol client to your X (Twitter) bookmarks. Search them semantically, count them, and manage labels through natural language.

Tweetsmash is a bookmark manager for X (Twitter): it imports the posts you bookmark on X into a searchable library, syncs them to Notion, Google Sheets, and Zotero, and exposes them to AI agents through this MCP server and an X bookmarks API.

Quick start

Create a Tweetsmash account at tweetsmash.com and import your X bookmarks (one click).
Generate an API token: Settings > Integrations > API.
Add the server to your MCP config:

json

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

Hosted endpoint (no local install)

Point any remote MCP client at:

code

https://mcp.tweetsmash.com/api/mcp

with your Tweetsmash API token as a Bearer header.

Tools

Tool	What it does
`list_bookmarks`	Page through saved posts with filters
`search_bookmarks`	Keyword and semantic search across every bookmark
`get_bookmark_count`	Count bookmarks, optionally by label
`list_labels`	List every label in your library
`add_labels_to_tweets`	Label bookmarks from your agent
`remove_labels_from_tweets`	Remove labels
`setup_vector_store`	Build the semantic search index

Example prompts

"Find my bookmarks about prompt engineering"
"How many bookmarks mention MCP?"
"Label everything I saved last week as AI"

License

MIT

Install

Tools (7)

list_bookmarkssearch_bookmarksget_bookmark_countlist_labelsadd_labels_to_tweetsremove_labels_from_tweetssetup_vector_store

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.tweetsmash.com/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.tweetsmash.com/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Topics

list_bookmarks

search_bookmarks

get_bookmark_count

list_labels

add_labels_to_tweets

remove_labels_from_tweets

setup_vector_store

Tweetsmash MCP Server: X (Twitter) Bookmarks for AI Agents

Quick start

Hosted endpoint (no local install)

Tools

Example prompts

Links

License

Install

Remote endpoint