@twitterapis/mcp 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.0 (2026-06-29)
+
+### Added
+
+- **Per-call inline credentials** for multi-account use: the 16 session tools (all writes + account-only reads) accept optional `auth_token` + `ct0` (plus optional `proxy_url` / `user_agent`) to act AS that account for a single call, with no pre-registered session, so one API key can act as many accounts. Sent as `x-auth-token` / `x-ct0` / `x-proxy-url` / `x-user-agent` request headers, never in the URL or query string.
+- For write actions, set `proxy_url` to a residential proxy: X soft-blocks writes that egress from datacenter IPs.
+
 ## 0.2.0 (2026-06-25)
 
 ### Added (full API parity)

package/README.md

@@ -89,7 +89,7 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 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.
 
-Public reads (search, profiles, tweets, followers) work with just your API key. The **account-only** reads (likes, 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). 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.
+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.
 
 ### Reads
 
@@ -201,7 +201,7 @@ count: 50
 
 ## Pricing
 
-Calls are billed to your twitterapis.com account at the standard read rate ($0.0008/call, or $0.04 per 1,000 tweets (each call returns about 20 tweets)); 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, 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).
 
 ## Links
 

package/package.json

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

@@ -38,21 +38,35 @@ if (!API_KEY) {
 // query string, so the same buildQuery path serves both; only the HTTP method
 // differs per tool.
 async function callEndpoint(path, args, method = "GET") {
-  const q = buildQuery(args);
+  // Pull per-call inline credentials out of args so they travel as request
+  // headers, never the query string (the API reads x-auth-token / x-ct0; passing
+  // them as query params would leak them into URLs and access logs). When
+  // supplied, this one API key acts as that account; otherwise the key's linked
+  // session is used. Lets a single key act as many accounts.
+  const { auth_token, ct0, user_agent, proxy_url, ...rest } = args || {};
+  const q = buildQuery(rest);
   const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
 
+  const headers = {
+    // The API accepts either header; send both for maximum compatibility.
+    Authorization: `Bearer ${API_KEY}`,
+    "x-api-key": API_KEY,
+    accept: "application/json",
+    "user-agent": "twitterapis-mcp/0.3.0",
+  };
+  if (auth_token && ct0) {
+    headers["x-auth-token"] = auth_token;
+    headers["x-ct0"] = ct0;
+    if (user_agent) headers["x-user-agent"] = user_agent;
+    if (proxy_url) headers["x-proxy-url"] = proxy_url;
+  }
+
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
   try {
     const res = await fetch(url, {
       method,
-      headers: {
-        // The API accepts either header; send both for maximum compatibility.
-        Authorization: `Bearer ${API_KEY}`,
-        "x-api-key": API_KEY,
-        accept: "application/json",
-        "user-agent": "twitterapis-mcp/0.2.0",
-      },
+      headers,
       signal: ctrl.signal,
     });
     const body = await res.text();
@@ -85,7 +99,7 @@ async function callEndpoint(path, args, method = "GET") {
 }
 
 // ── MCP server ───────────────────────────────────────────────────────────────
-const server = new McpServer({ name: "twitterapis", version: "0.2.0" });
+const server = new McpServer({ name: "twitterapis", version: "0.3.0" });
 
 for (const tool of TOOLS) {
   const method = tool.method || "GET";

package/src/tools.js

@@ -42,6 +42,25 @@ const ACCOUNT = {
     "Optional. The @handle (without @) of the authenticated account to act AS, when your key manages more than one session. Omit to use your key's default session.",
   ),
 };
+// Per-call inline credentials. Pass an account's own X session cookies to act AS
+// that account for this one call, without pre-registering a session, so a single
+// API key can act as many accounts (e.g. polling several inboxes or posting from
+// a pool). Sent as request headers, never in the URL. Omit to use the key's
+// linked session.
+const INLINE = {
+  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.",
+  ),
+};
 
 // ── Tool catalog. Reads are GET (default); writes set method:"POST". ─────────
 // write:true   -> action mutates account/Twitter state (annotated readOnlyHint:false)
@@ -223,6 +242,7 @@ export const TOOLS = [
         "Numeric user id of the target account to compute shared followers against.",
       ),
       ...PAGINATION,
+      ...INLINE,
     },
   },
   // ── Reads: a single tweet + its conversation ───────────────────────────────
@@ -272,14 +292,14 @@ export const TOOLS = [
     path: "/twitter/user/home_timeline",
     description:
       "Get YOUR authenticated account's Home timeline (the 'Following'/'For you' feed), most recent first. Requires an authenticated session behind your key. Returns tweets with author and metrics plus a cursor. Use this to read what your account would see when it opens X.",
-    shape: { ...PAGINATION },
+    shape: { ...PAGINATION, ...INLINE },
   },
   {
     name: "twitter_bookmarks",
     path: "/twitter/user/bookmarks",
     description:
       "List YOUR authenticated account's bookmarked tweets, most recent first. Requires an authenticated session behind your key. Returns each bookmarked tweet with author and metrics plus a cursor.",
-    shape: { ...PAGINATION },
+    shape: { ...PAGINATION, ...INLINE },
   },
   {
     name: "twitter_bookmark_search",
@@ -291,6 +311,7 @@ export const TOOLS = [
         "Search terms to match against your bookmarked tweets' text.",
       ),
       ...PAGINATION,
+      ...INLINE,
     },
   },
   {
@@ -298,7 +319,7 @@ export const TOOLS = [
     path: "/twitter/dm/list",
     description:
       "List YOUR authenticated account's Direct Message conversations (inbox), each with the participant and a conversation_id you can pass to twitter_dm_conversation. Requires an authenticated session behind your key. Read-only: this does not send DMs.",
-    shape: {},
+    shape: { ...INLINE },
   },
   {
     name: "twitter_dm_conversation",
@@ -309,6 +330,7 @@ export const TOOLS = [
       conversation_id: z.string().describe(
         "The conversation_id from a twitter_dm_list entry identifying which DM thread to read.",
       ),
+      ...INLINE,
     },
   },
 
@@ -333,7 +355,7 @@ export const TOOLS = [
       media_ids: z.string().optional().describe(
         "Optional. Comma-separated media id(s) from a prior media upload to attach (images/video).",
       ),
-      ...ACCOUNT,
+      ...ACCOUNT, ...INLINE,
     },
   },
   {
@@ -344,7 +366,7 @@ export const TOOLS = [
     destructive: true,
     description:
       "Delete a tweet AS your authenticated account. Irreversible: the tweet is permanently removed. You can only delete tweets your authenticated account authored. Provide the tweet id or url. Requires write capability behind your key.",
-    shape: { ...TWEET_REF, ...ACCOUNT },
+    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
   },
   // ── Writes: engagement (favorite / retweet / bookmark) + inverses ──────────
   {
@@ -354,7 +376,7 @@ export const TOOLS = [
     write: true,
     description:
       "Like (favorite) a tweet AS your authenticated account. Provide the tweet id or url. Requires write capability behind your key. Reverse with twitter_unfavorite_tweet.",
-    shape: { ...TWEET_REF, ...ACCOUNT },
+    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
   },
   {
     name: "twitter_unfavorite_tweet",
@@ -364,7 +386,7 @@ export const TOOLS = [
     destructive: true,
     description:
       "Remove a like (unfavorite) from a tweet AS your authenticated account. Provide the tweet id or url. Requires write capability behind your key.",
-    shape: { ...TWEET_REF, ...ACCOUNT },
+    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
   },
   {
     name: "twitter_retweet",
@@ -373,7 +395,7 @@ export const TOOLS = [
     write: true,
     description:
       "Retweet a tweet AS your authenticated account. Provide the tweet id or url. Requires write capability behind your key. Reverse with twitter_unretweet.",
-    shape: { ...TWEET_REF, ...ACCOUNT },
+    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
   },
   {
     name: "twitter_unretweet",
@@ -383,7 +405,7 @@ export const TOOLS = [
     destructive: true,
     description:
       "Undo a retweet AS your authenticated account. Provide the tweet id or url. Requires write capability behind your key.",
-    shape: { ...TWEET_REF, ...ACCOUNT },
+    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
   },
   {
     name: "twitter_bookmark_tweet",
@@ -392,7 +414,7 @@ export const TOOLS = [
     write: true,
     description:
       "Bookmark a tweet to YOUR authenticated account's private bookmarks. Provide the tweet id or url. Requires write capability behind your key. Reverse with twitter_unbookmark_tweet.",
-    shape: { ...TWEET_REF, ...ACCOUNT },
+    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
   },
   {
     name: "twitter_unbookmark_tweet",
@@ -402,7 +424,7 @@ export const TOOLS = [
     destructive: true,
     description:
       "Remove a tweet from YOUR authenticated account's bookmarks. Provide the tweet id or url. Requires write capability behind your key.",
-    shape: { ...TWEET_REF, ...ACCOUNT },
+    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
   },
   // ── Writes: follow graph ───────────────────────────────────────────────────
   {
@@ -416,7 +438,7 @@ export const TOOLS = [
       user_id: z.string().describe(
         "Numeric user id of the account to follow. Resolve a handle to a user_id first with twitter_user_info.",
       ),
-      ...ACCOUNT,
+      ...ACCOUNT, ...INLINE,
     },
   },
   {
@@ -431,7 +453,7 @@ export const TOOLS = [
       user_id: z.string().describe(
         "Numeric user id of the account to unfollow.",
       ),
-      ...ACCOUNT,
+      ...ACCOUNT, ...INLINE,
     },
   },
 ];