@twitterapis/mcp 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.5.0 (2026-07-06)
+
+### Added
+
+- `twitter_user_followers_v2` and `twitter_user_following_v2` — the v2 response shape (richer profile fields and more reliable cursoring for large follower/following audiences). Same inputs as the v1 tools (`username` / `user_id` + `cursor`). Catalog is now **40 tools** (29 reads + 11 write actions).
+
+### No breaking changes
+
 ## 0.3.0 (2026-06-29)
 
 ### Added

package/README.md

@@ -87,7 +87,7 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-37 tools: 27 reads and 10 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.
+40 tools: 29 reads and 11 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.
 
 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). 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.
 
@@ -110,6 +110,8 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_user_likes` | Tweets a user has liked (public Likes tab) |
 | `twitter_user_followers` | Accounts that follow a user |
 | `twitter_user_following` | Accounts a user follows |
+| `twitter_user_followers_v2` | Followers with the v2 response shape (richer fields, deeper cursoring) |
+| `twitter_user_following_v2` | Following with the v2 response shape (richer fields, deeper cursoring) |
 | `twitter_user_verified_followers` | A user's verified followers only |
 | `twitter_followers_you_know` | Followers of a target that your authenticated account also follows |
 | `twitter_tweet_detail` | Single tweet: text, author, metrics, media, quoted/reply context |
@@ -133,6 +135,7 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_retweet` / `twitter_unretweet` | Retweet / undo retweet |
 | `twitter_bookmark_tweet` / `twitter_unbookmark_tweet` | Bookmark / remove bookmark |
 | `twitter_follow_user` / `twitter_unfollow_user` | Follow / unfollow a user by id |
+| `twitter_dm_send` | Send a Direct Message to a user by their numeric `recipient_id` |
 
 ## Usage examples
 
@@ -201,7 +204,7 @@ count: 50
 
 ## Pricing
 
-Calls are billed to your twitterapis.com account, every price 20% below getxapi.com per endpoint. Almost every endpoint is $0.0008/call: all reads (search, profiles, tweets, followers, likes) plus the simple write actions (like, retweet, bookmark, follow and their undos, delete, media upload). At the read rate that works out to $0.04 per 1,000 tweets, since each call returns about 20 tweets. The premium endpoints cost a little more: tweet creation and DM reads (`twitter_dm_list`, `twitter_dm_conversation`) at $0.0016/call, profile updates (name, avatar, banner) at $0.0016/call, full tweet history (`twitter_user_tweets_complete`) at $0.0024/call, and a full tweet thread (`twitter_tweet_thread`) at $0.004/call. Your first $0.50 is free. See [twitterapis.com/pricing](https://www.twitterapis.com/pricing).
+Calls are billed to your twitterapis.com account, every price 20% below getxapi.com per endpoint. Almost every endpoint is $0.0008/call: all reads (search, profiles, tweets, followers, likes) plus the simple write actions (like, retweet, bookmark, follow and their undos, delete). At the read rate that works out to $0.04 per 1,000 tweets, since each call returns about 20 tweets. The premium endpoints cost a little more: tweet creation, sending a DM (`twitter_dm_send`), and DM reads (`twitter_dm_list`, `twitter_dm_conversation`) at $0.0016/call, full tweet history (`twitter_user_tweets_complete`) at $0.0024/call, and a full tweet thread (`twitter_tweet_thread`) at $0.004/call. Your first $0.50 is free. See [twitterapis.com/pricing](https://www.twitterapis.com/pricing).
 
 ## Links
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twitterapis/mcp",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "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

@@ -225,6 +225,20 @@ export const TOOLS = [
       "List the accounts that a given user follows. Returns profile data for each account followed. Paginate with cursor. Useful for mapping a user's information sources, influencer networks, or competitor monitoring lists.",
     shape: { ...USER_REF, ...PAGINATION },
   },
+  {
+    name: "twitter_user_followers_v2",
+    path: "/twitter/user/followers_v2",
+    description:
+      "List a user's followers using the v2 response shape (richer profile fields and more reliable cursoring for large audiences). Same inputs as twitter_user_followers; prefer this when you need the fuller v2 payload or are paging deep follower lists.",
+    shape: { ...USER_REF, ...PAGINATION },
+  },
+  {
+    name: "twitter_user_following_v2",
+    path: "/twitter/user/following_v2",
+    description:
+      "List the accounts a user follows using the v2 response shape (richer profile fields and more reliable cursoring). Same inputs as twitter_user_following; prefer this when you need the fuller v2 payload or are paging deep following lists.",
+    shape: { ...USER_REF, ...PAGINATION },
+  },
   {
     name: "twitter_user_verified_followers",
     path: "/twitter/user/verified_followers",
@@ -333,6 +347,23 @@ export const TOOLS = [
       ...INLINE,
     },
   },
+  {
+    name: "twitter_dm_send",
+    path: "/twitter/dm/send",
+    method: "POST",
+    write: true,
+    description:
+      "Send a Direct Message AS your authenticated account. Provide the recipient's numeric user id (recipient_id, resolve a @handle with twitter_user_info first) and the message text. Requires an authenticated session with write capability behind your key; X soft-blocks writes from datacenter IPs, so route through a residential proxy_url for reliability. Returns message_id and conversation_id. Delivers a real DM and is not silently reversible.",
+    shape: {
+      recipient_id: z.string().describe(
+        "Numeric Twitter/X user id of the recipient (e.g. '44196397'). Resolve a @handle to its id with twitter_user_info first. The recipient must allow DMs from you.",
+      ),
+      text: z.string().min(1).describe(
+        "The Direct Message body text to send (non-empty).",
+      ),
+      ...ACCOUNT, ...INLINE,
+    },
+  },
 
   // ── Writes: tweet authoring ────────────────────────────────────────────────
   {