@realaman90/x-mcp 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# x-mcp
+
+MCP server for X/Twitter API — give Claude (or any MCP client) the ability to search tweets, read profiles, get timelines, and read replies.
+
+**Read-only. No posting, liking, or following. Safe to use with AI agents.**
+
+## Why
+
+- Find engagement opportunities on X without leaving Claude
+- Study reply patterns and conversations around any topic
+- Research accounts, their content, and audience reactions
+- All read-only — no risk of accidental tweets or follows
+
+## Tools
+
+| Tool | Description | X API Endpoint |
+|------|-------------|----------------|
+| `search_tweets` | Search recent tweets (last 7 days) with full query operators | `GET /2/tweets/search/recent` |
+| `get_user_profile` | Get user profile by username (bio, followers, etc.) | `GET /2/users/by/username/{username}` |
+| `get_user_tweets` | Get a user's recent tweets by user ID | `GET /2/users/{id}/tweets` |
+| `get_tweet_replies` | Get replies to a specific tweet | Search `conversation_id:{id}` |
+| `get_tweet` | Get a single tweet with full details and metrics | `GET /2/tweets/{id}` |
+
+## Quick Start
+
+### 1. Get an X API Bearer Token
+
+1. Go to [developer.x.com](https://developer.x.com) and sign in
+2. Click **Developer Portal** → **Projects & Apps**
+3. Create a new **Project** (any name)
+4. Create an **App** inside the project
+5. Go to **Keys and Tokens** → generate a **Bearer Token**
+6. Copy the token — you'll need it in step 2
+
+> The **Basic** tier ($200/mo pay-per-usage) is sufficient. Free tier works too but has lower rate limits.
+
+### 2. Add to Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "x": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "x-mcp"],
+      "env": {
+        "X_BEARER_TOKEN": "your-bearer-token"
+      }
+    }
+  }
+}
+```
+
+### Or add to Claude Desktop
+
+Open **Settings** → **Developer** → **Edit Config** and add the same block above.
+
+### 3. Restart Claude and test
+
+```
+Search X for "AI agents" in English, no retweets
+```
+
+Claude will use the `search_tweets` tool automatically.
+
+## Usage Examples
+
+### Search tweets
+```
+"AI video" lang:en -is:retweet           # English tweets about AI video, no RTs
+from:elonmusk has:media                   # Elon's tweets with media
+#buildinpublic -is:reply                  # Hashtag, original tweets only
+"machine learning" has:links min_faves:10 # ML tweets with links, 10+ likes
+```
+
+### Chain tools together
+1. `get_user_profile` → get user ID from username
+2. `get_user_tweets` → get their recent tweets
+3. `get_tweet_replies` → see replies on a specific tweet
+
+### Run directly (without Claude)
+```bash
+X_BEARER_TOKEN="your-token" npx x-mcp
+```
+
+## Requirements
+
+- **Node.js 18+** (for native `fetch`)
+- **X API Bearer Token** — [Get one here](https://developer.x.com)
+
+## How It Works
+
+Single-file MCP server (~120 lines). No build step, no config files. Reads `X_BEARER_TOKEN` from environment, connects via stdio.
+
+```
+Claude ↔ stdio ↔ x-mcp ↔ X API v2
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const BEARER_TOKEN = decodeURIComponent(process.env.X_BEARER_TOKEN || "");
+if (!BEARER_TOKEN) {
+  console.error("X_BEARER_TOKEN environment variable is required");
+  process.exit(1);
+}
+
+const TWEET_FIELDS = "created_at,public_metrics,author_id,conversation_id,in_reply_to_user_id,lang";
+const USER_FIELDS = "created_at,description,public_metrics,profile_image_url,url,verified";
+
+async function xapi(endpoint, params = {}) {
+  const url = new URL(`https://api.x.com/2${endpoint}`);
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined) url.searchParams.set(k, String(v));
+  }
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${BEARER_TOKEN}` },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`X API ${res.status}: ${body}`);
+  }
+  return res.json();
+}
+
+const server = new McpServer({
+  name: "x-mcp",
+  version: "1.0.0",
+});
+
+// 1. Search tweets
+server.tool(
+  "search_tweets",
+  "Search recent tweets by keywords, hashtags, or advanced operators. Returns up to 100 tweets from the last 7 days.",
+  {
+    query: z.string().describe("Search query (supports X search operators like lang:en, -is:retweet, from:username)"),
+    max_results: z.number().min(10).max(100).default(10).describe("Number of results (10-100)"),
+  },
+  async ({ query, max_results }) => {
+    const data = await xapi("/tweets/search/recent", {
+      query,
+      max_results,
+      "tweet.fields": TWEET_FIELDS,
+      expansions: "author_id",
+      "user.fields": "username,name",
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// 2. Get user profile
+server.tool(
+  "get_user_profile",
+  "Get an X/Twitter user's profile by username. Returns bio, follower counts, and account details.",
+  {
+    username: z.string().describe("X username (without @)"),
+  },
+  async ({ username }) => {
+    const data = await xapi(`/users/by/username/${username}`, {
+      "user.fields": USER_FIELDS,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// 3. Get user's tweets
+server.tool(
+  "get_user_tweets",
+  "Get recent tweets from a specific user by their user ID. Use get_user_profile first to get the ID from a username.",
+  {
+    user_id: z.string().describe("X user ID (numeric string — get this from get_user_profile)"),
+    max_results: z.number().min(5).max(100).default(10).describe("Number of results (5-100)"),
+  },
+  async ({ user_id, max_results }) => {
+    const data = await xapi(`/users/${user_id}/tweets`, {
+      max_results,
+      "tweet.fields": TWEET_FIELDS,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// 4. Get tweet replies
+server.tool(
+  "get_tweet_replies",
+  "Get replies to a specific tweet using its conversation ID. Returns recent replies from the last 7 days.",
+  {
+    tweet_id: z.string().describe("Tweet ID to find replies for (used as conversation_id)"),
+    max_results: z.number().min(10).max(100).default(10).describe("Number of results (10-100)"),
+  },
+  async ({ tweet_id, max_results }) => {
+    const data = await xapi("/tweets/search/recent", {
+      query: `conversation_id:${tweet_id}`,
+      max_results,
+      "tweet.fields": TWEET_FIELDS,
+      expansions: "author_id",
+      "user.fields": "username,name",
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// 5. Get single tweet
+server.tool(
+  "get_tweet",
+  "Get a single tweet by ID with full details including metrics, author info, and conversation context.",
+  {
+    tweet_id: z.string().describe("Tweet ID"),
+  },
+  async ({ tweet_id }) => {
+    const data = await xapi(`/tweets/${tweet_id}`, {
+      "tweet.fields": TWEET_FIELDS,
+      expansions: "author_id",
+      "user.fields": "username,name",
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@realaman90/x-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for X/Twitter API — search tweets, read profiles, get timelines and replies",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "x-mcp": "index.js"
+  },
+  "keywords": ["mcp", "twitter", "x", "claude", "ai"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  }
+}