Metadata-Version: 2.4
Name: apitwitter-mcp
Version: 0.1.0
Summary: MCP server for the apitwitter.com Twitter/X API — use X/Twitter from Claude, Cursor and any MCP client.
Project-URL: Homepage, https://apitwitter.com
Project-URL: Documentation, https://docs.apitwitter.com
Project-URL: Repository, https://github.com/ApiTwitter/apitwitter-mcp
Author: apitwitter
License: MIT
License-File: LICENSE
Keywords: apitwitter,claude,llm,mcp,twitter,x
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# apitwitter-mcp

MCP server for the [apitwitter.com](https://apitwitter.com) Twitter/X API.
Lets Claude Desktop, Cursor, and any other MCP client use X/Twitter as
first-class tools: read timelines, search, post tweets, DMs, lists,
communities, topics, bookmarks, follows, likes — the full surface.

## What you need

1. An **apitwitter.com API key** — sign up at https://apitwitter.com.
2. An **x.com session cookie** (your logged-in X session) — this is what
   actions are performed as. You can pass it per tool call, or set a default
   via `APITWITTER_COOKIE`.

## Install

### Option A — `uvx` (zero-install, recommended)

```json
{
  "mcpServers": {
    "apitwitter": {
      "command": "uvx",
      "args": ["apitwitter-mcp"],
      "env": {
        "APITWITTER_KEY": "sk_live_...",
        "APITWITTER_COOKIE": "auth_token=...; ct0=..."
      }
    }
  }
}
```

### Option B — `pip`

```bash
pip install apitwitter-mcp
```

```json
{
  "mcpServers": {
    "apitwitter": {
      "command": "apitwitter-mcp",
      "env": {
        "APITWITTER_KEY": "sk_live_...",
        "APITWITTER_COOKIE": "auth_token=...; ct0=..."
      }
    }
  }
}
```

Place the snippet in:

- **Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
- **Cursor** — Settings → MCP → Add server
- Any other MCP-compatible client

Restart the client; the tools appear under the hammer icon.

## Environment variables

| Var | Required | Default | Purpose |
|---|---|---|---|
| `APITWITTER_KEY` | yes | — | Your apitwitter.com API key (sent as `X-API-Key`). |
| `APITWITTER_COOKIE` | no | — | Default x.com session cookie. Without it, every tool call must pass `cookie=`. |
| `APITWITTER_BASE` | no | `https://api.apitwitter.com` | Override for self-hosting / staging. |
| `APITWITTER_PROXY` | no | — | Default proxy URL for Twitter requests. |
| `APITWITTER_TIMEOUT` | no | `60` | HTTP timeout (seconds). |

## Tools

All endpoints of `/twitter/*` are exposed. Every tool accepts optional
`cookie` and `proxy` arguments that override the env defaults.

**Tweets** — `post_tweet`, `lookup_tweet`, `get_user_tweets`,
`get_for_you_timeline`, `get_latest_timeline`, `search_tweets`, `delete_tweet`,
`retweet`, `unretweet`, `pin_tweet`, `unpin_tweet`

**Users** — `verify_session`, `get_user`, `get_users_batch`, `get_user_by_id`,
`get_user_followers`, `get_user_following`, `get_user_likes`, `get_user_media`,
`get_user_replies`, `get_followers_you_know`, `remove_follower`,
`get_blocked_accounts`, `get_muted_accounts`

**Engagement** — `like_tweet`, `unlike_tweet`, `follow_user`, `unfollow_user`

**DMs** — `get_dm_inbox`, `get_xchat_token`, `get_dm_permissions`, `block_dm`,
`unblock_dm`, `send_dm`

**Bookmarks** — `bookmark_tweet`, `unbookmark_tweet`, `get_bookmarks`

**Lists** — `create_list`, `delete_list`, `get_owned_lists`,
`get_list_memberships`, `get_list_info`, `get_list_tweets`, `get_list_members`,
`add_list_member`, `remove_list_member`, `get_list_subscribers`,
`subscribe_list`, `unsubscribe_list`

**Communities** — `explore_communities`, `get_community`, `join_community`,
`leave_community`, `get_community_tweets`, `get_community_media`

**Topics** — `get_topic`, `follow_topic`, `unfollow_topic`

## Local development

```bash
git clone https://github.com/YOUR_ORG/apitwitter-mcp
cd apitwitter-mcp
python -m venv .venv && .venv\Scripts\activate   # Windows
pip install -e .

set APITWITTER_KEY=sk_live_...
set APITWITTER_COOKIE=auth_token=...; ct0=...
apitwitter-mcp                                   # stdio server
```

To point at a staging backend:

```bash
set APITWITTER_BASE=http://localhost:8000
```

## Publishing to PyPI (maintainers)

```bash
pip install build twine
python -m build
twine upload dist/*
```

After the first release, users can install via `pip install apitwitter-mcp`
or run with no install via `uvx apitwitter-mcp`.

## License

MIT
