@twitterapis/mcp 0.6.8 → 0.6.9

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.6.9 (2026-08-10)
+
+### Added
+
+- **2 new tools for X's bookmark folders** (task #9): `twitter_bookmark_folders` (list your own bookmark folders, X's internal name: collections) and `twitter_bookmark_folder_timeline` (read the tweets inside one specific folder, by `folder_id`). Both require an authenticated session, same auth model as `twitter_bookmarks` and `twitter_bookmark_search`. `twitter_bookmark_folder_timeline` is cursor-paginated only; there is no count/page-size argument for this op. The catalog is now **62 tools: 41 reads and 21 write actions**.
+
 ## 0.6.8 (2026-08-10)
 
 ### Added

package/README.md

@@ -91,7 +91,7 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-60 tools: 39 reads and 21 write actions. Most user endpoints accept `username` (handle without @) **or** `user_id` (`twitter_user_likes` and `twitter_user_tweets_complete` require `user_id`); tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page. Two of the reads are free account/billing lookups (`twitter_account_me`, `twitter_account_payments`).
+62 tools: 41 reads and 21 write actions. Most user endpoints accept `username` (handle without @) **or** `user_id` (`twitter_user_likes` and `twitter_user_tweets_complete` require `user_id`); tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page. Two of the reads are free account/billing lookups (`twitter_account_me`, `twitter_account_payments`).
 
 Public reads (search, profiles, tweets, followers, likes) work with just your API key. The **account-only** reads (bookmarks, DMs, home timeline, followers-you-know) and **all write actions** act AS an authenticated X account, so they need a session linked to your key first (returns HTTP 409 until then). Link a session either by registering your x.com cookies (`twitter_customer_session`) or by logging in with a username/password (`twitter_user_login`). Alternatively, pass **per-call inline credentials** on any of those tools (`auth_token` + `ct0`, with optional `proxy_url` / `user_agent`) to act AS that account for a single call without pre-registering a session, so one API key can act as many accounts. For write actions, set `proxy_url` to a residential proxy, since X soft-blocks writes that egress from datacenter IPs. Each write tool is annotated `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark) are annotated `destructiveHint: true` so MCP clients can prompt before running them.
 
@@ -129,6 +129,8 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_blocking` | Accounts your authenticated account has blocked (your own list only) _(session)_ |
 | `twitter_muting` | Accounts your authenticated account has muted (your own list only) _(session)_ |
 | `twitter_bookmark_search` | Full-text search within your bookmarks _(session)_ |
+| `twitter_bookmark_folders` | Your authenticated account's bookmark folders _(session)_ |
+| `twitter_bookmark_folder_timeline` | Tweets inside one of your bookmark folders, by `folder_id` _(session)_ |
 | `twitter_dm_list` | Your DM conversations (inbox), read-only _(session)_ |
 | `twitter_dm_conversation` | Messages in one DM conversation, read-only _(session)_ |
 | `twitter_trends` | Current top trends for a location (by `country` or `woeid`) |
@@ -255,7 +257,7 @@ Calls are billed to your twitterapis.com account. Almost every endpoint is $0.00
 
 **Do I need an X (Twitter) developer account?** No. Get an API key at [twitterapis.com/signup](https://www.twitterapis.com/signup); there is no application or approval step.
 
-**Is it read-only?** No. 39 read tools work with just your API key; 21 write actions (post, like, retweet, follow, DM, media upload, article create/edit/publish/delete) act as a linked X account or per-call inline credentials.
+**Is it read-only?** No. 41 read tools work with just your API key; 21 write actions (post, like, retweet, follow, DM, media upload, article create/edit/publish/delete) act as a linked X account or per-call inline credentials.
 
 **Which clients are supported?** Claude Desktop, Cursor, Windsurf, and VS Code (Copilot agent mode), or any Model Context Protocol client.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twitterapis/mcp",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "Official MCP server for twitterapis.com, the Twitter/X API (search, users, followers, tweets, threads, lists, likes, bookmarks, DMs) plus write actions (post/like/retweet/follow) as native tools for Claude, Cursor, and any MCP client.",
   "repository": {
     "type": "git",

package/src/tools.js

@@ -8,7 +8,7 @@
 // file in memory and fails if it does not match what is committed, so a hand edit
 // here is caught rather than shipped.
 //
-// Catalog: 60 tools (39 reads, 21 writes).
+// Catalog: 62 tools (41 reads, 21 writes).
 //
 // Each tool maps 1:1 to a REST endpoint at https://api.twitterapis.com. Tool arg
 // names map 1:1 to endpoint query params (every endpoint, including the POST
@@ -634,6 +634,52 @@ export const TOOLS = [
       ),
     },
   },
+  {
+    name: "twitter_bookmark_folders",
+    path: "/twitter/user/bookmark_folders",
+    description:
+      "List YOUR authenticated account's bookmark FOLDERS (X's internal name: collections), the named groups you can organize saved tweets into, separate from your flat bookmarks list (twitter_bookmarks). Requires an authenticated session behind your key. Returns each folder's id, name, and a cover image. Takes no arguments; your folders resolve from your session alone. Use twitter_bookmark_folder_timeline with a folder's id to read the tweets inside it.",
+    shape: {
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
+  {
+    name: "twitter_bookmark_folder_timeline",
+    path: "/twitter/user/bookmark_folder_timeline",
+    description:
+      "Read the tweets inside ONE of your authenticated account's bookmark folders, identified by folder_id (from twitter_bookmark_folders). Requires an authenticated session behind your key. Cursor-paginated; there is no count/page-size argument for this op.",
+    shape: {
+      folder_id: z.string().describe(
+        "The bookmark folder's id, from twitter_bookmark_folders (e.g. '2073826456430592429').",
+      ),
+      cursor: z.string().optional().describe(
+        "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
   {
     name: "twitter_dm_list",
     path: "/twitter/dm/list",