1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@x-mcp show me my timeline" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

x-mcp

by namank42

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

x-mcp

A Model Context Protocol (MCP) server for the X (Twitter) API. Built with the official @xdevplatform/xdk SDK and OAuth 2.0 PKCE authentication.

Features

23 tools across users, posts, bookmarks, likes, and lists
OAuth 2.0 PKCE with automatic token refresh
Dual output: markdown (human-readable) or JSON (structured)
MCP tool annotations: readOnlyHint, destructiveHint, idempotentHint

Related MCP server: TwitGhost

Prerequisites

Node.js v18+
pnpm
X API OAuth 2.0 credentials (Client ID and Secret)

Setup

Install dependencies:
```
pnpm install
```

Configure environment:

cp .env.example .env

Edit .env:

X_CLIENT_ID=your_oauth2_client_id
X_CLIENT_SECRET=your_oauth2_client_secret
X_REDIRECT_URI=http://localhost:3000/callback

Authenticate:
```
pnpm run setup-auth
```
Build:
```
pnpm run build
```

Getting X API Credentials

Go to the X Developer Portal
Create a Project and App
Enable OAuth 2.0 in app settings
Set app type to Web App
Add callback URL: http://localhost:3000/callback
Copy Client ID and Client Secret from the OAuth 2.0 section

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "x-mcp": {
      "command": "node",
      "args": ["/path/to/x-mcp/dist/index.js"],
      "env": {
        "X_TOKENS_PATH": "/path/to/x-mcp/.tokens.json",
        "X_CLIENT_ID": "your_client_id",
        "X_CLIENT_SECRET": "your_client_secret",
        "X_REDIRECT_URI": "http://localhost:3000/callback"
      }
    }
  }
}

Tools

Users

Tool	Description	Parameters
`x_get_user_profile`	Fetch a user profile by username	`username`, `response_format`
`x_get_my_profile`	Get the authenticated user's profile	`response_format`
`x_get_followers`	Get a user's followers	`username`, `limit`, `response_format`
`x_get_following`	Get accounts a user follows	`username`, `limit`, `response_format`

Posts

Tool	Description	Parameters
`x_get_user_posts`	Fetch recent posts from a user (excludes retweets/replies)	`username`, `limit`, `response_format`
`x_get_my_timeline`	Get your home timeline (reverse chronological)	`limit`, `response_format`
`x_search_posts`	Search recent posts (last 7 days)	`query`, `limit`, `response_format`

Bookmarks

Tool	Description	Parameters
`x_get_my_bookmarks`	Fetch your bookmarked posts	`limit`, `response_format`
`x_add_bookmark`	Bookmark a post	`tweet_id`
`x_remove_bookmark`	Remove a bookmark	`tweet_id`

Likes

Tool	Description	Parameters
`x_get_my_likes`	Fetch your liked posts	`limit`, `response_format`
`x_like_post`	Like a post	`tweet_id`
`x_unlike_post`	Unlike a post	`tweet_id`

Lists

Tool	Description	Parameters
`x_get_my_lists`	Get your owned lists	`response_format`
`x_get_list`	Get list details by ID	`list_id`, `response_format`
`x_get_list_posts`	Get posts from a list	`list_id`, `limit`, `response_format`
`x_get_list_members`	Get members of a list	`list_id`, `limit`, `response_format`
`x_create_list`	Create a new list	`name`, `description`, `private`
`x_update_list`	Update a list	`list_id`, `name`, `description`, `private`
`x_delete_list`	Delete a list	`list_id`
`x_add_list_member`	Add a user to a list	`list_id`, `username`
`x_remove_list_member`	Remove a user from a list	`list_id`, `username`

Project Structure

src/
├── index.ts              # MCP server entry point
├── constants.ts          # Shared constants
├── types.ts              # TypeScript interfaces
├── setup-auth.ts         # OAuth 2.0 setup flow
├── schemas/
│   └── common.ts         # Shared Zod schemas
├── services/
│   ├── auth-manager.ts   # OAuth 2.0 token management
│   └── x-client.ts       # X API client wrapper
├── tools/
│   ├── users.ts          # User profile tools
│   ├── tweets.ts         # Post/timeline tools
│   ├── bookmarks.ts      # Bookmark tools
│   ├── likes.ts          # Like tools
│   └── lists.ts          # List management tools
└── utils/
    └── formatting.ts     # Response formatting helpers

Scripts

Command	Description
`pnpm run build`	Compile TypeScript
`pnpm run dev`	Run in development mode
`pnpm start`	Run compiled server
`pnpm run setup-auth`	Authenticate with X
`pnpm run reset-auth`	Reset saved tokens

API Access Tiers

Tier	What works
Free	Post creation, basic read access
Basic ($200/mo)	All read/write endpoints, followers/following
Pro ($5,000/mo)	Higher rate limits, full search

License

MIT

Available Tools

22 tools

x_add_bookmarkBookmark PostA

Idempotent

Add a post to the authenticated user's bookmarks by its ID.

Inputs: tweet_id (required).

x_add_list_memberAdd List MemberB

Idempotent

Add a user to a list by their username and the list ID.

Inputs: list_id (required), username (required).

x_create_listCreate ListA

Create a new X list with a name, optional description, and privacy setting.

Inputs: name (required), private, description.

x_delete_listDelete ListA

Destructive

Permanently delete a list by its ID. This cannot be undone.

Inputs: list_id (required).

x_get_followersGet X User FollowersA

Read-onlyIdempotent

Get a list of users who follow a specified account. Returns usernames, bios, and follower counts.

Inputs: username (required), limit, response_format.

x_get_followingGet X User FollowingA

Read-onlyIdempotent

Get a list of users that a specified account follows. Returns usernames, bios, and follower counts.

Inputs: username (required), limit, response_format.

x_get_listGet List DetailsA

Read-onlyIdempotent

Get details of a specific list by its ID. Returns name, description, member/follower counts, and privacy.

Inputs: list_id (required), response_format.

x_get_list_membersGet List MembersB

Read-onlyIdempotent

Get members of a specific list by its ID.

Inputs: list_id (required), limit, response_format.

x_get_list_postsGet List PostsA

Read-only

Get recent posts from a specific list by its ID.

Inputs: list_id (required), limit, response_format.

x_get_my_bookmarksGet My BookmarksA

Read-onlyIdempotent

Fetch posts bookmarked by the authenticated user. Returns post text, engagement metrics, and timestamps.

Inputs: limit, response_format.

x_get_my_likesGet My Liked PostsA

Read-onlyIdempotent

Fetch posts liked by the authenticated user. Returns post text, engagement metrics, and timestamps.

Inputs: limit, response_format.

x_get_my_listsGet My ListsA

Read-onlyIdempotent

Get lists owned by the authenticated user. Returns list name, description, member/follower counts, and privacy.

Inputs: response_format.

x_get_my_profileGet My X ProfileA

Read-onlyIdempotent

Get the authenticated user's X profile including bio, metrics, and account info.

Inputs: response_format.

x_get_my_timelineGet My TimelineA

Read-only

Get the authenticated user's home timeline (reverse chronological). Includes posts from accounts you follow.

Inputs: limit, response_format.

x_get_user_postsGet User PostsA

Read-onlyIdempotent

Fetch recent posts from a user's timeline by username. Excludes retweets and replies.

Inputs: username (required), limit, response_format.

x_get_user_profileGet X User ProfileA

Read-onlyIdempotent

Fetch an X user profile by username. Returns bio, follower/following counts, post count, and account creation date.

Inputs: username (required), response_format.

x_like_postLike PostA

Idempotent

Like a post by its ID on behalf of the authenticated user.

Inputs: tweet_id (required).

x_remove_bookmarkRemove BookmarkA

DestructiveIdempotent

Remove a post from the authenticated user's bookmarks by its ID.

Inputs: tweet_id (required).

x_remove_list_memberRemove List MemberA

DestructiveIdempotent

Remove a user from a list by their username and the list ID.

Inputs: list_id (required), username (required).

x_search_postsSearch PostsA

Read-onlyIdempotent

Search for recent posts (last 7 days) matching a query. Supports keywords, hashtags, and X search operators.

Inputs: query (required), limit, response_format.

x_unlike_postUnlike PostA

DestructiveIdempotent

Remove a like from a post by its ID on behalf of the authenticated user.

Inputs: tweet_id (required).

x_update_listUpdate ListA

Idempotent

Update an existing list's name, description, or privacy. Provide at least one field to change.

Inputs: list_id (required), name, private, description.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored 2026-08-09 21:40 across 22 tools

Disambiguation5/5

Every tool targets a distinct resource and action. For example, x_get_user_profile vs x_get_my_profile clearly separate public vs authenticated profiles, and x_get_user_posts vs x_get_my_timeline distinguish a user's own posts from the home feed. No two tools have overlapping or ambiguous purposes.

Naming Consistency5/5

All tools follow a consistent x_ prefix with an action_noun pattern. Actions (get, search, add, remove, like, unlike, create, update, delete) are used uniformly, and the resource nouns are clear. The consistent style makes it easy to predict tool names.

Tool Count3/5

With 22 tools, the set falls into the 16-25 range, which feels heavy. While each tool serves a distinct purpose and covers many X features, the count is above the typical well-scoped 3-15 range, making it borderline. The abundance of list-related tools (7) contributes to the heaviness.

Completeness2/5

The server covers read operations, bookmarks, likes, and full list management, but it lacks core X actions like creating posts, replying, retweeting, and following/unfollowing users. This is a significant gap that would prevent agents from performing fundamental social media interactions, limiting the server's usefulness.

Maintenance

ActivityInactive

ResponsivenessOutdated data

Resources

Related MCP Connectors

mcp-serverA
io.twitterapi
Official twitterapi.io hosted MCP: Twitter/X tweets, users, followers, trends. OAuth or API key.
Social Media Search
121
https://mcp.twitterapi.io/v1/mcp
TwitterAPI.io MCP ServerA
io.github.kaitoInfra
Hosted MCP server from TwitterAPI.io that gives AI agents read-only access to Twitter/X data. 12 tools: tweet search with X operators, user profiles, a user's latest tweets, followers and followings, replies, quotes, retweeters, mentions and trends. Connect at https://mcp.twitterapi.io/mcp with a TwitterAPI.io API key or account sign-in; usage is paid per result returned.
Search Social Media
121
https://mcp.twitterapi.io/mcp
mcpA
com.tweetsmash
Search, label, and manage your X (Twitter) bookmarks from any MCP client via Tweetsmash
Social Media Search
532
https://mcp.tweetsmash.com/api/mcp
TwitterAPIs
io.github.TwitterAPIs
Official MCP server for twitterapis.com. Twitter/X search, users, DMs, Grok, monitoring and writes.
Social Media Communication Search
16
https://api.twitterapis.com/mcp

Related MCP Servers

xengager-mcp
Social Media Browser Automation
ogunbaysal
A
license
Not graded
quality
D
maintenance
Provides programmatic X (Twitter) engagement via MCP, offering 24 tools for search, timelines, notifications, bookmarks, profiles, and tweet actions through a headless browser.
Updated 5 months ago (2026-06-19 19:39 UTC)
MIT
TwitGhost
Social Media Communication
arvinmoj
A
license
B
quality
D
maintenance
Enables interacting with Twitter/X through natural language, including searching tweets, posting, sending DMs, and managing timelines via any MCP client.
Updated 5 months ago (2026-06-19 07:46 UTC)
8
MIT
social-mcp
Social Media Communication
vigneshsai890
A
license
Not graded
quality
C
maintenance
Provides MCP tools for social media, including publishing posts and retrieving analytics via X (Twitter) API v2, with OAuth token management and rate-limit handling.
Updated a month ago (2026-10-17 20:32 UTC)
38 npm
Apache 2.0
x-mcp
Social Media Communication
RobertDWhite
F
license
Not graded
quality
C
maintenance
Enables MCP-based interaction with the X (Twitter) API v2, supporting reads like timeline, mentions, and search, and writes through a two-step draft-and-confirm process that ensures human-visible previews before any public post.
Updated 3 months ago (2026-08-26 03:22 UTC)
-

x-mcp

Features

Prerequisites

Setup

Getting X API Credentials

Claude Desktop Integration

Tools

Users

Posts

Bookmarks

Likes

Lists

Project Structure

Scripts

API Access Tiers

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

xengager-mcp

TwitGhost

social-mcp

x-mcp