Metadata-Version: 2.4
Name: virtuals-tweepy-mcp
Version: 0.1.1
Summary: MCP server for X (Twitter) via Virtuals GAME SDK - 37 tools for tweets, search, users, and engagement
Project-URL: Homepage, https://github.com/kyoungrok0517/virtuals-tweepy-mcp
Project-URL: Repository, https://github.com/kyoungrok0517/virtuals-tweepy-mcp
Project-URL: Issues, https://github.com/kyoungrok0517/virtuals-tweepy-mcp/issues
Author-email: Kyoungrok Jang <kyoungrok.jang@gmail.com>
License-Expression: MIT
Keywords: agent,ai,game-sdk,llm,mcp,twitter,virtuals,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.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: mcp>=1.0.0
Requires-Dist: playwright>=1.57.0
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: twitter-plugin-gamesdk>=0.2.11
Requires-Dist: virtuals-tweepy>=0.1.6
Provides-Extra: article
Requires-Dist: playwright>=1.40.0; extra == 'article'
Description-Content-Type: text/markdown

# virtuals-tweepy-mcp

MCP server for X (Twitter) via Virtuals Protocol's GAME SDK. Provides 37 tools for AI agents to search tweets, post content, manage engagement, and more—with higher rate limits than standard Twitter API.

## Quick Start

### 1. Get Credentials

1. Register at [GAME Console](https://console.game.virtuals.io/)
2. Create a project and get your API key
3. Run OAuth to get Twitter access token:

   ```bash
   uvx virtuals-tweepy-mcp auth
   ```

### 2. Add to Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "twitter": {
      "command": "uvx",
      "args": ["virtuals-tweepy-mcp"],
      "env": {
        "GAME_API_KEY": "your-api-key",
        "GAME_TWITTER_ACCESS_TOKEN": "apx-your-token"
      }
    }
  }
}
```

Restart Claude Desktop. You now have 37 Twitter tools available.

## Available Tools

| Category       | Tools                                                                                                                                                       |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Search**     | `search_recent_tweets`, `search_spaces`                                                                                                                     |
| **Tweets**     | `get_tweet`, `post_tweet`, `delete_tweet`, `quote_tweet`                                                                                                    |
| **Replies**    | `reply_to_tweet`, `get_tweet_replies`                                                                                                                       |
| **Engagement** | `like_tweet`, `unlike_tweet`, `retweet`, `unretweet`, `bookmark_tweet`, `unbookmark_tweet`                                                                  |
| **Users**      | `get_user_by_username`, `get_users_by_usernames`, `get_my_profile`                                                                                          |
| **Timelines**  | `get_user_tweets`, `get_user_mentions`, `get_home_timeline`                                                                                                 |
| **Follow**     | `follow_user`, `unfollow_user`, `get_followers`, `get_following`                                                                                            |
| **Lists**      | `get_list`, `get_owned_lists`, `get_list_tweets`, `get_list_members`, `create_list`, `update_list`, `delete_list`, `add_list_member`, `remove_list_member`  |
| **DMs**        | `get_dm_conversations`, `get_dm_messages`, `send_dm`                                                                                                        |
| **Media**      | `upload_media`                                                                                                                                              |

## CLI Usage

The package also includes a CLI (`vobs`) for direct Twitter interaction:

```bash
# Install
uvx virtuals-tweepy-mcp

# Or with uv/pip
uv pip install virtuals-tweepy-mcp

# Commands
vobs me                              # Your profile
vobs search "bitcoin"                # Search tweets
vobs timeline elonmusk               # User's tweets
vobs user VitalikButerin             # User info
vobs mentions                        # Your mentions
vobs home                            # Home timeline
vobs post "Hello world!"             # Post tweet
vobs fetch <tweet-url>               # Fetch tweet with media URLs
```

## Search Syntax

Supports Twitter's advanced operators:

```bash
vobs search "from:elonmusk crypto"           # Tweets by user
vobs search "#AI min_faves:100 lang:en"      # High-engagement
vobs search "(ETH OR BTC) -scam has:links"   # Complex queries
```

| Operator | Example | Description |
|----------|---------|-------------|
| `from:` | `from:user` | By user |
| `to:` | `to:user` | Replies to |
| `#tag` | `#AI` | Hashtag |
| `min_faves:` | `min_faves:100` | Min likes |
| `has:media` | `has:media` | Has images/video |
| `-term` | `-scam` | Exclude |
| `OR` | `ETH OR BTC` | Either term |

## Rate Limits

- **Tier 1**: 50 calls / 5 minutes
- **Tier 2**: Higher limits (requires Virtuals approval)

## License

MIT
