X Platform Interface Utility Server

This is a Model Context Protocol (MCP) integration layer specifically engineered for interfacing with the X (Twitter) ecosystem, offering essential tooling for timeline consumption and direct social interaction. It is optimized for deployment alongside the Claude desktop application environment.

Capabilities

• Retrieve posts from the personalized home stream
• Programmatically author and dispatch new micro-posts
• Respond to established threads/posts
• Erase previously published posts
• Integrated defense mechanisms against X API rate limits applicable to the free usage plan
• Complete implementation in TypeScript ensuring rigorous static type verification

Prerequisites for Operation

• Runtime environment: Node.js (version 16 or newer)
• Authenticated X (Twitter) Developer Account (Free Tier subscription required)
• Claude desktop client installation

Accessing the X API (Free Tier Details)

X furnishes a complimentary access level for foundational API functionalities:

Complimentary Feature Set & Quotas

• Posting Volume Cap:
• 500 transmissions permitted monthly per individual user identity
• 500 transmissions permitted monthly per application instance
• Reading Quota:
• 100 data retrievals allowed per month
• Endpoint Availability:
• Access to the v2 posting APIs
• Endpoints for media asset uploading
• Access rights to the Ads API suite
• Limited to utilizing a single application identifier
• Support for 'Login with X' features
• Throttling Policy:
• Access to all endpoints is subject to periodic rate restrictions
• Limits undergo periodic resetting

Note: For enterprise or high-throughput requirements, premium subscriptions are available (e.g., Basic tier at $100/month offering 50,000 tweets/month, Pro tier at $5000/month with enhanced capacity).

You may enroll in the free tier via: https://developer.x.com/en/portal/products/free

Deployment Procedure

1. Obtain the source code repository:

git clone [your-repo-url]
cd x-mcp-server

1. Install necessary software packages:

npm install

1. Compile the server codebase:

npm run build

Configuration of Credentials

Setting up your X (Twitter) authentication credentials is mandatory. Adhere strictly to these sequenced instructions:

1. Navigate to the Twitter Developer Portal
2. Authenticate using your X account credentials

3. If necessary, complete the process to establish a developer account

4. Secure the Free Tier Subscription:

5. Direct your browser to https://developer.x.com/en/portal/products/free
6. Select the "Subscribe" option for the Free Access level

7. Finalize the required registration steps

8. Initiate a new Project Container:

9. Click the "Create Project" button
10. Assign a descriptive name (e.g., "Claude MCP Hookup")
11. Designate "Free" for the setup type
12. Specify your intended application use case

13. Proceed by clicking "Next"

14. Establish an Application within the Project:

15. Select the "Create App" option
16. Provide a unique application identifier name

17. Conclude the setup by clicking "Complete Setup"

18. Configure Application Parameters:

19. Within your application's administrative panel, select "App Settings"

20. Under the "User authentication settings" section:

    • Activate the configuration by clicking "Set Up"
    • Enable OAuth 1.0a protocol
    • Choose the appropriate application type ("Web App" or "Native App")
    • Input a placeholder URL for callback handling (e.g., https://example.com/callback)
    • Input a placeholder URL for the associated website (e.g., https://example.com)
    • Apply changes by clicking "Save"

21. Define Application Permissions:

22. In the app settings interface, locate "App permissions"
23. Modify permissions to grant "Read and Write" capabilities

24. Commit the alteration by clicking "Save"

25. Generate Authentication Tokens and Keys:

26. Navigate to the "Keys and Tokens" tab
27. Within the "Consumer Keys" block:
    • Reveal the secrets by clicking "View Keys" or use "Regenerate"
    • Securely record the API Key and the corresponding API Key Secret
28. Within the "Access Token and Secret" block:
    • Generate the required tokens by clicking "Generate"
    • Ensure the generated tokens possess the necessary "Read and Write" scope
    • Securely record the Access Token and the Access Token Secret

Critical Security Reminder: - Treat your retrieved keys and tokens with the highest confidentiality; do not expose them in public repositories. - You require all four unique credentials for successful operation: - API Key (Interchangeably known as Consumer Key) - API Key Secret (Interchangeably known as Consumer Secret) - Access Token - Access Token Secret - Recall the quantitative constraints of the free service tier: - 500 outgoing transmissions monthly (user-level) - 500 outgoing transmissions monthly (application-level) - 100 data retrieval operations monthly

Integration with Claude Desktop Environment

To establish a connection between this X MCP service and the Claude desktop client, specific configuration adjustments within Claude's settings file are necessary.

1. Access the operating system's file explorer.
2. Locate the directory reserved for Claude configuration:
3. On Windows: Press Win + R, enter %APPDATA%/Claude, and execute.

4. If the 'Claude' subdirectory is absent, manually construct it.

5. Create or modify the file named claude_desktop_config.json:

6. If the file is non-existent, generate a new file titled claude_desktop_config.json.

7. If the file already exists, open it using a plain text editor.

8. Inject the subsequent configuration structure, substituting the bracketed placeholders with the actual authentication material derived from the preceding section:

{
  "mcpServers": {
    "x": {
      "command": "node",
      "args": ["%USERPROFILE%/Projects/MCP Basket/x-server/build/index.js"],
      "env": {
        "TWITTER_API_KEY": "paste-your-api-key-here",
        "TWITTER_API_SECRET": "paste-your-api-key-secret-here",
        "TWITTER_ACCESS_TOKEN": "paste-your-access-token-here",
        "TWITTER_ACCESS_SECRET": "paste-your-access-token-secret-here"
      }
    }
  }
}

1. Save the modified file and subsequently restart the Claude desktop application.

Configuration Checkpoints: - Ensure that every one of the four placeholder credential strings is replaced with your valid keys/tokens. - Verify that all string values remain enclosed in double quotation marks ("). - Maintain the precise indentation and structural layout as presented. - Confirm the file is saved explicitly with the .json file extension.

Exposed Toolset

get_home_timeline

Fetches the most recent set of transmissions appearing in the user's designated home feed.

Parameters: - limit (Optional): Specifies the maximum quantity of posts to pull (Default: 20; Maximum permissible: 100)

Usage Example:

await use_mcp_tool({
  server_name: "x",
  tool_name: "get_home_timeline",
  arguments: { limit: 5 }
});

create_tweet

Compiles and publishes a completely new status update to the platform.

Parameters: - text (Mandatory): The textual payload of the micro-post (Maximum length: 280 characters)

Usage Example:

await use_mcp_tool({
  server_name: "x",
  tool_name: "create_tweet",
  arguments: { text: "Greetings from the MCP utility! 🤖" }
});

reply_to_tweet

Submits a textual response directed at an existing piece of content.

Parameters: - tweet_id (Mandatory): The unique identifier of the post being responded to - text (Mandatory): The text content intended for the reply (Maximum length: 280 characters)

Usage Example:

await use_mcp_tool({
  server_name: "x",
  tool_name: "reply_to_tweet",
  arguments: {
    tweet_id: "1234567890",
    text: "Excellent point made! 👍"
  }
});

delete_tweet

Permanently removes a previously posted item identified by its ID. Parameters: - tweet_id (Mandatory): The unique ID associated with the post slated for deletion Usage Example:

await use_mcp_tool({
  server_name: "x",
  tool_name: "delete_tweet",
  arguments: {
    tweet_id: "1234567890"
  }
});

Development Lifecycle Commands

• npm run build: Executes the compilation process for the TypeScript source files.
• npm run dev: Initiates TypeScript execution in continuous watch mode for development.
• npm start: Launches the operational MCP interface service.

Throttling Management System

This server incorporates internal logic to gracefully manage the constraints imposed by X's complimentary usage tier: - Monthly Usage Ceilings: - 500 outgoing transmissions/month (User scope) - 500 outgoing transmissions/month (Application scope) - 100 incoming reads/month - Managed Features: - Continuous tracking of accrued monthly consumption metrics - Implementation of an exponential backoff strategy upon encountering rate limit errors - Provides explicit diagnostic messages upon reaching service quotas - Automatic scheduling of retries once the enforced rate limit window has elapsed

Licensing

This project is distributed under the MIT License.

Contribution Guidelines

1. Fork the primary repository.
2. Establish a dedicated feature branch (git checkout -b feature/my-new-enhancement).
3. Commit your modifications (git commit -m 'Implement feature X').
4. Push the branch to the remote origin (git push origin feature/my-new-enhancement).
5. Submit a formal Pull Request for review.

WIKIPEDIA: XMLHttpRequest (XHR) is an application programming interface, presented as a JavaScript object, whose primary function is to facilitate the transmission of HTTP requests from a web browser environment to a designated web server. This object's methods empower browser-based applications to dispatch requests to the server subsequent to initial page rendering, and subsequently process the received data. XMLHttpRequest forms a crucial element of the Ajax programming paradigm. Before Ajax gained prominence, server interaction was predominantly executed via traditional hyperlinks or form submissions, actions that typically necessitated a complete page reload or navigation to a different view.

== Chronology == The fundamental concept underlying XMLHttpRequest was first conceptualized in the year 2000 by the development team responsible for Microsoft Outlook. This principle was subsequently instantiated within the Internet Explorer 5 browser release (1999). Crucially, the initial syntax employed by Microsoft did not utilize the standardized XMLHttpRequest identifier; instead, developers relied upon the constructor calls ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of the release of Internet Explorer 7 (2006), universal browser adoption of the formal XMLHttpRequest identifier was achieved. The XMLHttpRequest identifier has since cemented its status as the prevailing standard across all major browser engines, including Mozilla's Gecko rendering engine (adopted around 2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Specification Evolution === The World Wide Web Consortium (W3C) formally published an initial Working Draft specification detailing the XMLHttpRequest object on April 5, 2006. Subsequently, on February 25, 2008, the W3C released the Working Draft Level 2 specification. Level 2 introduced substantial enhancements, such as methods for monitoring data transfer progress, support for cross-site resource invocation, and capability to manage raw byte streams. By the conclusion of 2011, the features defined in the Level 2 specification were integrated directly into the primary specification document. At the close of 2012, stewardship for the specification documentation transitioned to the WHATWG, which now maintains the document as a living standard formalized using Web IDL definitions.

== Typical Utilization Pattern == Generally, executing a network request utilizing XMLHttpRequest necessitates adherence to several distinct programming phases.

1. Instantiate the XMLHttpRequest object by invoking its constructor:
2. Invoke the open() method to define the request method (GET, POST, etc.), specify the target URI, and select between synchronous or asynchronous operation mode:
3. For asynchronous operations, register an event handler function that will be triggered upon subsequent state transitions of the request:
4. Commence the data transfer by calling the send() method, optionally including a request body:
5. Monitor the state changes within the registered event handler. If the server successfully returns payload data, this content is typically housed within the responseText property by default. When the object completes all processing of the response, its state transitions to 4, designated as the "done" state. Beyond these fundamental steps, XMLHttpRequest provides extensive configuration parameters to govern request dispatching and response processing methodology. Custom HTTP header fields can be prepended to the outgoing request to convey specific server instructions, and data payloads can be transmitted to the server by supplying them as an argument to the send() call. The incoming response data can be automatically parsed from JSON format into a natively usable JavaScript object structure, or it can be processed incrementally as chunks arrive, bypassing the need to await the complete text buffer. Furthermore, operations can be terminated prematurely via an abort command or configured to automatically time out if completion is not achieved within a preset duration.