@twitterapis/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 twitterapis.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @twitterapis/mcp
+
+Official **Model Context Protocol** server for [twitterapis.com](https://www.twitterapis.com) — the Twitter / X **read** API as native tools for Claude, Cursor, and any MCP client.
+
+Ask your agent to *"find the latest tweets about AI agents"* or *"pull @openai's followers"* and it calls the API directly. Every tool maps to a REST endpoint at `https://api.twitterapis.com`; the server holds no state and forwards your API key per call.
+
+## Install
+
+No install needed — run it on demand with `npx`. You only need an API key (free `$0.50` in credits, no card): **https://www.twitterapis.com/signup**.
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "twitterapis": {
+      "command": "npx",
+      "args": ["-y", "@twitterapis/mcp@latest"],
+      "env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (or Settings → MCP → Add):
+
+```json
+{
+  "mcpServers": {
+    "twitterapis": {
+      "command": "npx",
+      "args": ["-y", "@twitterapis/mcp@latest"],
+      "env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
+    }
+  }
+}
+```
+
+Restart the client and the `twitter_*` tools appear.
+
+## Configuration
+
+| Env var | Required | Default | Purpose |
+|---|---|---|---|
+| `TWITTERAPIS_KEY` | ✅ | — | Your API key from the dashboard |
+| `TWITTERAPIS_BASE_URL` | | `https://api.twitterapis.com` | Override the API host |
+| `TWITTERAPIS_TIMEOUT_MS` | | `30000` | Per-request timeout |
+
+## Tools
+
+All read-only. User endpoints take `username` **or** `user_id`; tweet endpoints take `id` **or** `url`; list endpoints page with `count` + `cursor`.
+
+| Tool | What it does |
+|---|---|
+| `twitter_advanced_search` | Search tweets with X operators (`from:`, `min_faves:`, `filter:`, …) |
+| `twitter_user_search` | Search accounts by name/keyword |
+| `twitter_user_info` | Full profile by handle |
+| `twitter_user_info_by_id` | Full profile by numeric id |
+| `twitter_user_tweets` | A user's recent tweets (no replies) |
+| `twitter_user_tweets_and_replies` | A user's full timeline (tweets + replies) |
+| `twitter_user_followers` | Accounts that follow a user |
+| `twitter_user_following` | Accounts a user follows |
+| `twitter_user_verified_followers` | A user's verified followers |
+| `twitter_user_media` | Media a user has posted |
+| `twitter_user_mentions` | Recent tweets mentioning a user |
+| `twitter_tweet_detail` | One tweet's full detail |
+| `twitter_tweet_replies` | Replies to a tweet |
+| `twitter_tweet_thread` | A tweet's self-thread |
+| `twitter_tweet_retweeters` | Accounts that retweeted a tweet |
+| `twitter_list_members` | Members of a List |
+
+## Pricing
+
+Calls are billed to your twitterapis.com account at the standard read rate (`$0.0008`/call); your first `$0.50` is free. See [pricing](https://www.twitterapis.com/pricing).
+
+## Links
+
+- Docs — https://docs.twitterapis.com
+- Dashboard / keys — https://www.twitterapis.com/dashboard
+- REST API (no MCP needed) — https://api.twitterapis.com
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@twitterapis/mcp",
+  "version": "0.1.0",
+  "description": "Official MCP server for twitterapis.com — the Twitter/X read API (search, users, followers, tweets, threads, lists) as native tools for Claude, Cursor, and any MCP client.",
+  "type": "module",
+  "bin": {
+    "twitterapis-mcp": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "check": "node --check src/index.js && node --check src/tools.js",
+    "test": "node test/tools.test.mjs && node test/smoke.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8 || ^4.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "twitter",
+    "x",
+    "twitter-api",
+    "x-api",
+    "claude",
+    "cursor",
+    "twitterapis"
+  ],
+  "author": "twitterapis.com",
+  "license": "MIT",
+  "homepage": "https://www.twitterapis.com/mcp",
+  "bugs": {
+    "url": "https://www.twitterapis.com/contact"
+  }
+}

package/src/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// @twitterapis/mcp — official MCP server for twitterapis.com
+//
+// Exposes the Twitter / X READ API as native MCP tools (search, users,
+// followers/following, tweets, threads, lists, mentions) for Claude, Cursor,
+// and any MCP client. Each tool is a thin, typed wrapper over a REST endpoint
+// at https://api.twitterapis.com — the server holds no state and forwards your
+// API key on every call. The tool catalog lives in ./tools.js.
+//
+// Config (env):
+//   TWITTERAPIS_KEY        required — your key from https://www.twitterapis.com/signup
+//   TWITTERAPIS_BASE_URL   optional — defaults to https://api.twitterapis.com
+//   TWITTERAPIS_TIMEOUT_MS optional — per-request timeout (default 30000)
+//
+// Run:  npx -y @twitterapis/mcp@latest   (stdio transport)
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TOOLS, buildQuery } from "./tools.js";
+
+const API_KEY = process.env.TWITTERAPIS_KEY;
+const BASE_URL = (
+  process.env.TWITTERAPIS_BASE_URL || "https://api.twitterapis.com"
+).replace(/\/+$/, "");
+const REQUEST_TIMEOUT_MS = Number(process.env.TWITTERAPIS_TIMEOUT_MS || 30000);
+
+if (!API_KEY) {
+  console.error(
+    "[twitterapis-mcp] Missing TWITTERAPIS_KEY. Get a key at https://www.twitterapis.com/signup and set it in your MCP client config.",
+  );
+  process.exit(1);
+}
+
+// ── REST call ────────────────────────────────────────────────────────────────
+async function callEndpoint(path, args) {
+  const q = buildQuery(args);
+  const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: "GET",
+      headers: {
+        // The API accepts either header; send both for maximum compatibility.
+        Authorization: `Bearer ${API_KEY}`,
+        "x-api-key": API_KEY,
+        accept: "application/json",
+        "user-agent": "twitterapis-mcp/0.1.0",
+      },
+      signal: ctrl.signal,
+    });
+    const body = await res.text();
+    if (!res.ok) {
+      const hint =
+        res.status === 401
+          ? " (check TWITTERAPIS_KEY)"
+          : res.status === 402
+            ? " (insufficient credits — top up at https://www.twitterapis.com/dashboard)"
+            : res.status === 429
+              ? " (rate limited — retry shortly)"
+              : "";
+      return { isError: true, content: [{ type: "text", text: `HTTP ${res.status}${hint}: ${body.slice(0, 1200)}` }] };
+    }
+    return { content: [{ type: "text", text: body }] };
+  } catch (err) {
+    const msg = err?.name === "AbortError" ? `timed out after ${REQUEST_TIMEOUT_MS}ms` : err?.message || String(err);
+    return { isError: true, content: [{ type: "text", text: `Request failed: ${msg}` }] };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── MCP server ───────────────────────────────────────────────────────────────
+const server = new McpServer({ name: "twitterapis", version: "0.1.0" });
+
+for (const tool of TOOLS) {
+  server.registerTool(
+    tool.name,
+    { description: tool.description, inputSchema: tool.shape },
+    async (args) => callEndpoint(tool.path, args),
+  );
+}
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Logs go to stderr so they never corrupt the stdio JSON-RPC stream.
+  console.error(`[twitterapis-mcp] ready · ${TOOLS.length} tools · base ${BASE_URL}`);
+}
+
+main().catch((err) => {
+  console.error("[twitterapis-mcp] fatal:", err);
+  process.exit(1);
+});

package/src/tools.js

@@ -0,0 +1,79 @@
+// Tool catalog + pure query-builder for @twitterapis/mcp.
+// Kept separate from the server wiring (index.js) so it can be unit-tested
+// without spawning the stdio transport.
+import { z } from "zod";
+
+// ── Shared Zod input-schema fragments ───────────────────────────────────────
+const PAGINATION = {
+  count: z.number().int().positive().optional().describe("Max items to return for this page (endpoint default applies if omitted)."),
+  cursor: z.string().optional().describe("Pagination cursor returned by a previous call to fetch the next page."),
+};
+const USER_REF = {
+  username: z.string().optional().describe('Twitter/X handle, without the leading @ (e.g. "elonmusk"). Provide this OR user_id.'),
+  user_id: z.string().optional().describe("Numeric user id. Provide this OR username."),
+};
+const TWEET_REF = {
+  id: z.string().optional().describe('Tweet id (e.g. "1789..."). Provide this OR url.'),
+  url: z.string().optional().describe("Full tweet URL (https://x.com/<user>/status/<id>). Provide this OR id."),
+};
+
+// ── Read-only tool catalog. Tool arg names map 1:1 to endpoint query params. ─
+export const TOOLS = [
+  { name: "twitter_advanced_search", path: "/twitter/tweet/advanced_search",
+    description: "Search recent tweets with X's advanced-search syntax (operators like from:, to:, since:, until:, min_faves:, filter:). Returns matching tweets with author, metrics, and a cursor for paging.",
+    shape: { query: z.string().describe('Search query, e.g. "AI agents min_faves:100" or "from:openai".'), product: z.enum(["Top", "Latest", "Media", "People"]).optional().describe('Result tab. "Latest" for reverse-chron, "Top" for ranked (default).'), ...PAGINATION } },
+  { name: "twitter_user_search", path: "/twitter/user/search",
+    description: "Search for users/accounts by name or keyword. Returns matching profiles with a paging cursor.",
+    shape: { query: z.string().describe("Name or keyword to search accounts for."), ...PAGINATION } },
+  { name: "twitter_user_info", path: "/twitter/user/info",
+    description: "Get a user's full profile by handle: bio, follower/following counts, verification, location, created date, pinned tweet.",
+    shape: { username: z.string().describe("Twitter/X handle without the leading @.") } },
+  { name: "twitter_user_info_by_id", path: "/twitter/user/info_by_id",
+    description: "Get a user's full profile by numeric user id (use when you have the id but not the handle).",
+    shape: { user_id: z.string().describe("Numeric user id.") } },
+  { name: "twitter_user_tweets", path: "/twitter/user/tweets",
+    description: "Get a user's recent original tweets (no replies). Cursored.",
+    shape: { ...USER_REF, ...PAGINATION } },
+  { name: "twitter_user_tweets_and_replies", path: "/twitter/user/tweets_and_replies",
+    description: "Get a user's recent tweets AND replies (their full timeline). Cursored.",
+    shape: { ...USER_REF, ...PAGINATION } },
+  { name: "twitter_user_followers", path: "/twitter/user/followers",
+    description: "List the accounts that follow a user. Cursored.",
+    shape: { ...USER_REF, ...PAGINATION } },
+  { name: "twitter_user_following", path: "/twitter/user/following",
+    description: "List the accounts a user follows. Cursored.",
+    shape: { ...USER_REF, ...PAGINATION } },
+  { name: "twitter_user_verified_followers", path: "/twitter/user/verified_followers",
+    description: "List a user's verified (blue/business) followers. Cursored.",
+    shape: { ...USER_REF, ...PAGINATION } },
+  { name: "twitter_user_media", path: "/twitter/user/media",
+    description: "Get the media (images/videos) a user has posted. Cursored.",
+    shape: { ...USER_REF, ...PAGINATION } },
+  { name: "twitter_user_mentions", path: "/twitter/user/mentions",
+    description: "Get recent tweets that mention a user (implemented as a to:<username> search). Cursored.",
+    shape: { username: z.string().describe("Twitter/X handle without the leading @."), ...PAGINATION } },
+  { name: "twitter_tweet_detail", path: "/twitter/tweet/detail",
+    description: "Get a single tweet's full detail: text, author, metrics, media, and quoted/replied context.",
+    shape: { ...TWEET_REF } },
+  { name: "twitter_tweet_replies", path: "/twitter/tweet/replies",
+    description: "Get the replies to a tweet. Cursored.",
+    shape: { ...TWEET_REF, ...PAGINATION } },
+  { name: "twitter_tweet_thread", path: "/twitter/tweet/thread",
+    description: "Get the full self-thread for a tweet (the author's connected chain). Cursored.",
+    shape: { ...TWEET_REF, ...PAGINATION } },
+  { name: "twitter_tweet_retweeters", path: "/twitter/tweet/retweeters",
+    description: "List the accounts that retweeted a tweet. Cursored.",
+    shape: { ...TWEET_REF, ...PAGINATION } },
+  { name: "twitter_list_members", path: "/twitter/list/members",
+    description: "List the members of a Twitter/X List by list id. Cursored.",
+    shape: { list_id: z.string().describe("Numeric List id."), ...PAGINATION } },
+];
+
+// Pure query-string builder: drops undefined/null/empty values, URL-encodes the rest.
+export function buildQuery(args) {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(args || {})) {
+    if (v !== undefined && v !== null && String(v).length > 0) qs.set(k, String(v));
+  }
+  return qs.toString();
+}