X MCP server for AI agents

Let Claude, ChatGPT or your own agent read and act on X: 28 typed functions through one MCP server. No X API key needed.

Site
x.com
Functions
28
Sign-in
For account actions
Works with
MCP, HTTP, Node, Python

Connect

Just X

An MCP server for X alone, with one tool per function. Paste it into Claude, ChatGPT, Cursor or any MCP client as a remote server.

https://api.bowmark.ai/mcp/site/x
Every site

One MCP server for X and every other site Bowmark covers. Your agent looks up what it needs and calls it.

https://api.bowmark.ai/mcp
Set it up in your client

Both need a Bowmark API key. The quickstart gets you one and a first result in a few minutes. Functions that need a login use the person's own account: how sign-in works.

Functions

Open a function to see its arguments, what it returns and how to call it.

Read 14
  • getConversationThe messages inside one of the signed-in account's DM conversations.

    Arguments

    NameTypeRequired
    conversationIdstring
    From listConversations' id.
    Yes
    limitnumberNo

    Returns XDirectMessageRow[]

    interface XDirectMessageRow {
      text: string;
      createdAt: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/getConversation

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.getConversation({ conversationId: "123-456" });
  • getListPostsThe posts in an X List, read as the signed-in caller.

    Arguments

    NameTypeRequired
    args{ listId: string; limit?: number }Yes

    Returns XTweet[]

    interface XTweet {
      id: string;
      text: string;
      createdAt: string;
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/getListPosts

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.getListPosts({ listId: "1585430245762441216" });
  • getPostRepliesReads the reply thread under a single X post.

    Arguments

    NameTypeRequired
    urlstringNo
    idstringNo
    limitnumberNo

    Returns XTweet[]

    interface XTweet {
      id: string;
      text: string;
      createdAt: string;
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/getPostReplies

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.getPostReplies({ id: "1585341984679469056", limit: 3 });
  • listBookmarksThe signed-in account's saved bookmarks.

    Arguments

    NameTypeRequired
    args{ limit?: number }No

    Returns XTweet[]

    interface XTweet {
      id: string;
      text: string;
      createdAt: string;
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/listBookmarks

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.listBookmarks({});
  • listConversationsThe signed-in account's direct-message conversation list.

    Arguments

    NameTypeRequired
    args{ limit?: number }No

    Returns XConversation[]

    interface XConversation {
      id: string;
      participants: string[]; // handles, no @
      lastMessageText: string;
      lastMessageAt: string | null;
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/listConversations

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.listConversations({});
  • listFollowersA user's followers list.

    Arguments

    NameTypeRequired
    handlestringYes
    limitnumberNo

    Returns XUserSummary[]

    interface XUserSummary {
      handle: string; // no @
      name: string;
      bio: string;
      avatarUrl: string | null;
      verified: boolean;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/listFollowers

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.listFollowers({ handle: "X" });
  • listFollowingWho a user follows.

    Arguments

    NameTypeRequired
    handlestringYes
    limitnumberNo

    Returns XUserSummary[]

    interface XUserSummary {
      handle: string; // no @
      name: string;
      bio: string;
      avatarUrl: string | null;
      verified: boolean;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/listFollowing

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.listFollowing({ handle: "X" });
  • listHomeFeedThe signed-in account's personalized home timeline, in X's own order.

    Arguments

    NameTypeRequired
    args{ limit?: number }No

    Returns XTweet[]

    interface XTweet {
      id: string;
      text: string;
      createdAt: string;
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/listHomeFeed

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.listHomeFeed({});
  • listListsThe X Lists an account owns, follows or belongs to, each with the id getListPosts takes.

    Arguments

    NameTypeRequired
    args{ handle: string; limit?: number }Yes

    Returns XListSummary[]

    interface XListSummary {
      id: string; // pass to getListPosts
      name: string;
      url: string;
      memberCount: number | null;
      ownerHandle: string | null; // no @
      description: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/listLists

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.listLists({ handle: "NASA" });
  • listNotificationsThe signed-in account's notifications.

    Arguments

    NameTypeRequired
    args{ limit?: number }No

    Returns XNotification[]

    interface XNotification {
      type: "like" | "repost" | "follow" | "reply" | "mention" | "quote" | "other";
      text: string;
      actors: string[]; // handles, no @
      postId: string | null;
      postUrl: string | null;
      createdAt: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/listNotifications

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.listNotifications({});
  • listTrendingThe site's current trending topics, the /explore page.

    Arguments

    NameTypeRequired
    args{ limit?: number }No

    Returns XTrend[]

    interface XTrend {
      name: string;
      context: string | null; // e.g. "Trending in Technology", when the site shows one
      postVolume: string | null; // the site's own rounded string, e.g. "20.1K posts"
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/listTrending

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.listTrending({});
  • profileReads an X (Twitter) profile by handle or profile URL.

    Arguments

    NameTypeRequired
    args{ handle: string }Yes

    Returns XProfile

    interface XProfile {
      handle: string;
      name: string;
      bio: string;
      location: string;
      url: string;
      website: string | null;
      followers: number;
      following: number;
      tweets: number;
      joined: string;
      verified: boolean;
      avatarUrl: string;
      mentions: string[]; // handles the bio @-mentions, without the "@"
      links: string[]; // every link on the profile, expanded (website first, then bio urls)
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/profile

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.profile({ handle: "X" });
  • userTimelineReads a public user account's recent timeline to find posts, scrolling until limit is met or the feed runs out.

    Arguments

    NameTypeRequired
    handlestringYes
    limitnumberNo

    Returns XTweet[]

    interface XTweet {
      id: string;
      text: string;
      createdAt: string;
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/userTimeline

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.userTimeline({ handle: "X" });
Act 14
  • blockUserBlock or unblock an account as the signed-in account.

    Arguments

    NameTypeRequired
    args{ handle: string; block?: boolean }Yes

    Returns XRelationResult

    interface XRelationResult {
      handle: string;
      state: boolean; // true when blocked (blockUser) / muted (muteUser) after the call
      changed: boolean; // false when it was already in that state
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/blockUser

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.blockUser({});
  • bookmarkPostBookmark or un-bookmark a post as the signed-in account.

    Arguments

    NameTypeRequired
    args{ url?: string; id?: string; bookmark?: boolean }Yes

    Returns XToggleResult

    interface XToggleResult {
      postId: string;
      state: boolean; // the state after the call
      changed: boolean; // false when it was already in that state
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/bookmarkPost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.bookmarkPost({});
  • createPostPost a new tweet as the signed-in account, optionally with up to four photos. text may be left out when images is set (a photo-only post).

    Arguments

    NameTypeRequired
    args{ text?: string; images?: XPostImage[] }Yes
    /** One photo for a post: an https URL, or the bytes base64-encoded (jpeg/png/webp/gif). */
    type XPostImage = { imageUrl: string } | { base64: string; mimeType?: string };

    Returns XPostWriteResult

    interface XPostWriteResult {
      posted: true;
      text: string;
      url: string | null; // the new post, when X's confirmation toast links it
      inReplyTo: string | null; // post id
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/createPost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.createPost({});
  • deletePostDelete one of the signed-in account's own posts.

    Arguments

    NameTypeRequired
    args{ url?: string; id?: string }Yes

    Returns XDeletePostResult

    interface XDeletePostResult {
      postId: string;
      deleted: true;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/deletePost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.deletePost({});
  • followUserFollow or unfollow a user as the signed-in account.

    Arguments

    NameTypeRequired
    args{ handle: string; follow?: boolean }Yes

    Returns XFollowResult

    interface XFollowResult {
      handle: string;
      following: boolean; // true when the caller follows the account after the call
      changed: boolean; // false when it was already in that state
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/followUser

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.followUser({});
  • likePostLike or unlike a post as the signed-in account.

    Arguments

    NameTypeRequired
    args{ url?: string; id?: string; like?: boolean }Yes

    Returns XToggleResult

    interface XToggleResult {
      postId: string;
      state: boolean; // the state after the call
      changed: boolean; // false when it was already in that state
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/likePost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.likePost({});
  • muteUserMute or unmute an account as the signed-in account.

    Arguments

    NameTypeRequired
    args{ handle: string; mute?: boolean }Yes

    Returns XRelationResult

    interface XRelationResult {
      handle: string;
      state: boolean; // true when blocked (blockUser) / muted (muteUser) after the call
      changed: boolean; // false when it was already in that state
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/muteUser

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.muteUser({});
  • postReads detailed engagement metrics and media details for a single X (Twitter) post or tweet by URL or ID.

    Arguments

    NameTypeRequired
    args{ url: string } | { id: string }Yes

    Returns XPost

    interface XPostMedia {
      type: "photo" | "video" | "gif";
      url: string;
      thumbnailUrl: string | null;
      width: number | null;
      height: number | null;
      durationMs: number | null;
    }
    
    interface XPost {
      id: string;
      url: string;
      text: string;
      createdAt: string;
      author: { handle: string; name: string; followers: number };
      views: number | null; // null on posts older than X's view counter
      likes: number;
      reposts: number;
      replies: number;
      quotes: number;
      bookmarks: number;
      lang: string | null;
      replyingTo: string | null;
      media: XPostMedia[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/post

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.post({});
  • quotePostQuote-repost a post with the signed-in account's own added comment.

    Arguments

    NameTypeRequired
    args{ url?: string; id?: string; text: string }Yes

    Returns XQuotePostResult

    interface XQuotePostResult {
      posted: true;
      text: string;
      url: string | null; // the new post, when X's confirmation toast links it
      quotedPostId: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/quotePost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.quotePost({});
  • replyToPostReply to another post as the signed-in account, optionally with up to four photos. text may be left out when images is set (a photo-only reply).

    Arguments

    NameTypeRequired
    args{ url?: string; id?: string; text?: string; images?: XPostImage[] }Yes
    /** One photo for a post: an https URL, or the bytes base64-encoded (jpeg/png/webp/gif). */
    type XPostImage = { imageUrl: string } | { base64: string; mimeType?: string };

    Returns XPostWriteResult

    interface XPostWriteResult {
      posted: true;
      text: string;
      url: string | null; // the new post, when X's confirmation toast links it
      inReplyTo: string | null; // post id
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/replyToPost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.replyToPost({});
  • repostRepost (retweet) or un-repost a post as the signed-in account.

    Arguments

    NameTypeRequired
    args{ url?: string; id?: string; repost?: boolean }Yes

    Returns XToggleResult

    interface XToggleResult {
      postId: string;
      state: boolean; // the state after the call
      changed: boolean; // false when it was already in that state
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/repost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.repost({});
  • sendDirectMessageSend a direct message (DM) to an X user by handle as the signed-in account, starting a new conversation or continuing an existing one.

    Arguments

    NameTypeRequired
    handlestring
    "@jack", "jack" or a profile URL.
    Yes
    textstringYes

    Returns XDirectMessageResult

    interface XDirectMessageResult {
      sent: true;
      to: string; // handle, no @
      text: string;
      conversationUrl: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/sendDirectMessage

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.sendDirectMessage({ handle: "<handle>", text: "<text>" });
  • updateProfileEdit the signed-in account's own profile.

    Arguments

    NameTypeRequired
    namestringNo
    biostringNo
    locationstringNo
    websitestringNo

    Returns XUpdateProfileResult

    interface UpdateProfileArgs {
      name?: string;
      bio?: string;
      location?: string;
      website?: string;
    }
    
    interface XUpdateProfileResult {
      updated: true;
      fields: UpdateProfileArgs;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/updateProfile

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.updateProfile({});
  • uploadProfilePictureChange the signed-in account's own profile picture.

    Arguments

    NameTypeRequired
    imageUrlstring
    Https JPEG/PNG/WebP/GIF.
    No
    base64stringNo
    mimeTypestringNo

    Returns XUploadProfilePictureResult

    interface XUploadProfilePictureResult {
      updated: true;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/x/uploadProfilePicture

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.x.uploadProfilePicture({});

Use it from code