Skip to content
Back to search

xmcp

MCP server for the X API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xdevplatform--xmcp/badge.svg)](/listings/xdevplatform--xmcp)

HTML

<a href="/listings/xdevplatform--xmcp"><img src="/api/listings/xdevplatform--xmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Create a virtual environment and install dependencies: - `python -m venv .venv` - `source .venv/bin/activate` - `pip install -r requirements.txt` 2. Create your local `.env`: - `cp env.example .env` - Required values (do not skip): - `X_OAUTH_CONSUMER_KEY` - `X_OAUTH_CONSUMER_SECRET` - `X_BEARER_TOKEN` (required for this setup; keep it set even if using OAuth1) - OAuth1 callback (defaults are fine): - `X_OAUTH_CALLBACK_HOST` (default `127.0.0.1`) - `X_OAUTH_CALLBACK_PORT` (default `8976`) - `X_OAUTH_CALLBACK_PATH` (default `/oauth/callback`) - `X_OAUTH_CALLBACK_TIMEOUT` (default `300`) - Server settings (optional): - `X_API_BASE_URL` (default `https://api.x.com`) - `X_API_TIMEOUT` (default `30`) - `MCP_HOST` (default `127.0.0.1`) - `MCP_PORT` (default `8000`) - `X_API_DEBUG` (default `1`) - Tool filtering (optional, comma-separated): - `X_API_TOOL_ALLOWLIST` - Optional Grok test client: - `XAI_API_KEY` - `XAI_MODEL` (default `grok-4-1-fast`) - `MCP_SERVER_URL` (default `http://127.0.0.1:8000/mcp`) - Optional OAuth2 token generation: - `CLIENT_ID` - `CLIENT_SECRET` - `X_OAUTH_ACCESS_TOKEN` - `X_OAUTH_ACCESS_TOKEN_SECRET` (optional) - Optional OAuth1 debug output: - `X_OAUTH_PRINT_TOKENS` - `X_OAUTH_PRINT_AUTH_HEADER` 3. Register the callback URL in your X Developer App:

http://<X_OAUTH_CALLBACK_HOST>:<X_OAUTH_CALLBACK_PORT><X_OAUTH_CALLBACK_PATH>

Example (defaults):

http://127.0.0.1:8976/oauth/callback

4. Start the server:

python server.py

The MCP endpoint is `http://127.0.0.1:8000/mcp` by default.

5. Connect an MCP client: - Local client: point it to `http://127.0.0.1:8000/mcp`. - Remote client: tunnel your local server (e.g., ngrok) and use the public URL.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 240 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # X API FastMCP Server
  2. Run a local MCP server that exposes the X API OpenAPI spec as tools using
  3. FastMCP. Streaming and webhook endpoints are excluded.
  4. ## Prerequisites
  5. - Python 3.9+
  6. - An X Developer Platform app (to get tokens)
  7. - Optional: an xAI API key if you want to run the Grok test client
  8. ## Setup (local)
  9. 1. Create a virtual environment and install dependencies:
  10. - `python -m venv .venv`
  11. - `source .venv/bin/activate`
  12. - `pip install -r requirements.txt`
  13. 2. Create your local `.env`:
  14. - `cp env.example .env`
  15. - Required values (do not skip):
  16. - `X_OAUTH_CONSUMER_KEY`
  17. - `X_OAUTH_CONSUMER_SECRET`
  18. - `X_BEARER_TOKEN` (required for this setup; keep it set even if using OAuth1)
  19. - OAuth1 callback (defaults are fine):
  20. - `X_OAUTH_CALLBACK_HOST` (default `127.0.0.1`)
  21. - `X_OAUTH_CALLBACK_PORT` (default `8976`)
  22. - `X_OAUTH_CALLBACK_PATH` (default `/oauth/callback`)
  23. - `X_OAUTH_CALLBACK_TIMEOUT` (default `300`)
  24. - Server settings (optional):
  25. - `X_API_BASE_URL` (default `https://api.x.com`)
  26. - `X_API_TIMEOUT` (default `30`)
  27. - `MCP_HOST` (default `127.0.0.1`)
  28. - `MCP_PORT` (default `8000`)
  29. - `X_API_DEBUG` (default `1`)
  30. - Tool filtering (optional, comma-separated):
  31. - `X_API_TOOL_ALLOWLIST`
  32. - Optional Grok test client:
  33. - `XAI_API_KEY`
  34. - `XAI_MODEL` (default `grok-4-1-fast`)
  35. - `MCP_SERVER_URL` (default `http://127.0.0.1:8000/mcp`)
  36. - Optional OAuth2 token generation:
  37. - `CLIENT_ID`
  38. - `CLIENT_SECRET`
  39. - `X_OAUTH_ACCESS_TOKEN`
  40. - `X_OAUTH_ACCESS_TOKEN_SECRET` (optional)
  41. - Optional OAuth1 debug output:
  42. - `X_OAUTH_PRINT_TOKENS`
  43. - `X_OAUTH_PRINT_AUTH_HEADER`
  44. 3. Register the callback URL in your X Developer App:
  45. ```
  46. http://<X_OAUTH_CALLBACK_HOST>:<X_OAUTH_CALLBACK_PORT><X_OAUTH_CALLBACK_PATH>
  47. ```
  48. Example (defaults):
  49. ```
  50. http://127.0.0.1:8976/oauth/callback
  51. ```
  52. 4. Start the server:
  53. ```
  54. python server.py
  55. ```
  56. The MCP endpoint is `http://127.0.0.1:8000/mcp` by default.
  57. 5. Connect an MCP client:
  58. - Local client: point it to `http://127.0.0.1:8000/mcp`.
  59. - Remote client: tunnel your local server (e.g., ngrok) and use the public URL.
  60. ## Whitelisting tools
  61. Use `X_API_TOOL_ALLOWLIST` to load a small, explicit set of tools:
  62. ```
  63. X_API_TOOL_ALLOWLIST=getUsersByUsername,createPosts,searchPostsRecent
  64. ```
  65. Whitelisting is applied at startup when the OpenAPI spec is loaded, so restart
  66. the server after changes. See the full tool list below before building your
  67. allowlist.
  68. ## OAuth1 flow (startup behavior)
  69. On startup, the server opens a browser for OAuth1 consent and waits for the
  70. callback. Tokens are kept in memory only for the lifetime of the server
  71. process. Set `X_OAUTH_PRINT_TOKENS=1` to print tokens, or
  72. `X_OAUTH_PRINT_AUTH_HEADER=1` to print request headers.
  73. ## Available tool calls (allowlist-ready)
  74. Below is the full list of tool calls you can whitelist via
  75. `X_API_TOOL_ALLOWLIST`. Copy any of these into your `.env` allowlist.
  76. - `addListsMember`
  77. - `addUserPublicKey`
  78. - `appendMediaUpload`
  79. - `blockUsersDms`
  80. - `createCommunityNotes`
  81. - `createComplianceJobs`
  82. - `createDirectMessagesByConversationId`
  83. - `createDirectMessagesByParticipantId`
  84. - `createDirectMessagesConversation`
  85. - `createLists`
  86. - `createMediaMetadata`
  87. - `createMediaSubtitles`
  88. - `createPosts`
  89. - `createUsersBookmark`
  90. - `deleteActivitySubscription`
  91. - `deleteAllConnections`
  92. - `deleteCommunityNotes`
  93. - `deleteConnectionsByEndpoint`
  94. - `deleteConnectionsByUuids`
  95. - `deleteDirectMessagesEvents`
  96. - `deleteLists`
  97. - `deleteMediaSubtitles`
  98. - `deletePosts`
  99. - `deleteUsersBookmark`
  100. - `evaluateCommunityNotes`
  101. - `finalizeMediaUpload`
  102. - `followList`
  103. - `followUser`
  104. - `getAccountActivitySubscriptionCount`
  105. - `getActivitySubscriptions`
  106. - `getChatConversation`
  107. - `getChatConversations`
  108. - `getCommunitiesById`
  109. - `getComplianceJobs`
  110. - `getComplianceJobsById`
  111. - `getConnectionHistory`
  112. - `getDirectMessagesEvents`
  113. - `getDirectMessagesEventsByConversationId`
  114. - `getDirectMessagesEventsById`
  115. - `getDirectMessagesEventsByParticipantId`
  116. - `getInsights28Hr`
  117. - `getInsightsHistorical`
  118. - `getListsById`
  119. - `getListsFollowers`
  120. - `getListsMembers`
  121. - `getListsPosts`
  122. - `getMarketplaceHandleAvailability`
  123. - `getMediaAnalytics`
  124. - `getMediaByMediaKey`
  125. - `getMediaByMediaKeys`
  126. - `getMediaUploadStatus`
  127. - `getNews`
  128. - `getOpenApiSpec`
  129. - `getPostsAnalytics`
  130. - `getPostsById`
  131. - `getPostsByIds`
  132. - `getPostsCountsAll`
  133. - `getPostsCountsRecent`
  134. - `getPostsLikingUsers`
  135. - `getPostsQuotedPosts`
  136. - `getPostsRepostedBy`
  137. - `getPostsReposts`
  138. - `getSpacesBuyers`
  139. - `getSpacesByCreatorIds`
  140. - `getSpacesById`
  141. - `getSpacesByIds`
  142. - `getSpacesPosts`
  143. - `getTrendsByWoeid`
  144. - `getTrendsPersonalizedTrends`
  145. - `getUsage`
  146. - `getUserPublicKeys`
  147. - `getUsersAffiliates`
  148. - `getUsersBlocking`
  149. - `getUsersBookmarkFolders`
  150. - `getUsersBookmarks`
  151. - `getUsersBookmarksByFolderId`
  152. - `getUsersById`
  153. - `getUsersByIds`
  154. - `getUsersByUsername`
  155. - `getUsersByUsernames`
  156. - `getUsersFollowedLists`
  157. - `getUsersFollowers`
  158. - `getUsersFollowing`
  159. - `getUsersLikedPosts`
  160. - `getUsersListMemberships`
  161. - `getUsersMe`
  162. - `getUsersMentions`
  163. - `getUsersMuting`
  164. - `getUsersOwnedLists`
  165. - `getUsersPinnedLists`
  166. - `getUsersPosts`
  167. - `getUsersRepostsOfMe`
  168. - `getUsersTimeline`
  169. - `hidePostsReply`
  170. - `initializeMediaUpload`
  171. - `likePost`
  172. - `mediaUpload`
  173. - `muteUser`
  174. - `pinList`
  175. - `removeListsMemberByUserId`
  176. - `repostPost`
  177. - `searchCommunities`
  178. - `searchCommunityNotesWritten`
  179. - `searchEligiblePosts`
  180. - `searchNews`
  181. - `searchPostsAll`
  182. - `searchPostsRecent`
  183. - `searchSpaces`
  184. - `searchUsers`
  185. - `sendChatMessage`
  186. - `unblockUsersDms`
  187. - `unfollowList`
  188. - `unfollowUser`
  189. - `unlikePost`
  190. - `unmuteUser`
  191. - `unpinList`
  192. - `unrepostPost`
  193. - `updateActivitySubscription`
  194. - `updateLists`
  195. ## Generate an OAuth2 user token (optional)
  196. 1. Add `CLIENT_ID` and `CLIENT_SECRET` to your `.env`.
  197. 2. Update `redirect_uri` in `generate_authtoken.py` to match your app settings.
  198. 3. Run `python generate_authtoken.py` and follow the prompts.
  199. 4. Copy the printed access token into `.env` as `X_OAUTH_ACCESS_TOKEN`.
  200. If your flow returns a secret, store it as `X_OAUTH_ACCESS_TOKEN_SECRET`.
  201. ## Run the Grok MCP test client (optional)
  202. 1. Set `XAI_API_KEY` in `.env`.
  203. 2. Make sure your MCP server is running locally (or set `MCP_SERVER_URL`).
  204. 3. If Grok is not running on your machine, use ngrok to expose your local MCP
  205. server and set `MCP_SERVER_URL` to the public HTTPS URL that ends with `/mcp`.
  206. Example flow: `ngrok http 8000` then `MCP_SERVER_URL=https://<id>.ngrok-free.dev/mcp`.
  207. 4. Run `python test_grok_mcp.py`.
  208. ## Notes
  209. - Endpoints with `/stream` or `/webhooks` in the path are excluded.
  210. - Operations tagged `Stream` or `Webhooks`, or marked with
  211. `x-twitter-streaming: true`, are excluded.
  212. - The OpenAPI spec is fetched from `https://api.twitter.com/2/openapi.json` at
  213. startup.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.