# TwitterShots MCP Server

MCP (Model Context Protocol) server for generating Twitter/X tweet screenshots using the TwitterShots API.

## How to Use

### 1. Get Your API Key

1. Visit [TwitterShots Account Settings](https://twittershots.com/account/settings)
2. Navigate to Account Settings > API Key
3. Copy your API key for configuration

**API Usage Limits:**

- Free & Pro: 5 screenshots for trial
- Pro+: 300 screenshots per month
- Business: 6,000 screenshots per month

### 2. Install and Configure

1. Clone or download the TwitterShots MCP Server from the repository:
   ```bash
   git clone git@github.com:twittershots/twittershots-mcp.git
   cd twittershots-mcp
   ```
   Or download the project as a ZIP file and extract it to your desired location.

### 3. Configure MCP Client

Add the server to your MCP client configuration (e.g., Cursor, Claude Desktop) in your MCP config file:

**For Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "twittershots": {
      "command": "node",
      "args": ["/path/to/twittershots-mcp/build/index.js"],
      "env": {
        "TWITTERSHOTS_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Example mcp.json with actual path:**
```json
{
  "mcpServers": {
    "twittershots": {
      "command": "node",
      "args": ["/Users/0xinhua/workspace/open-source/0xinhua-proj/twittershots-mcp/build/index.js"],
      "env": {
        "TWITTERSHOTS_API_KEY": "sk_xxxxxx"
      }
    }
  }
}
```

### 4. Start Using with Natural Language

Once configured, you can use natural language to generate tweet screenshots and check API usage:

- "Use twittershots to screenshot https://x.com/elonmusk/status/2001742502332911922 in dark mode"
- "Generate a screenshot of tweet 2002397336803348716 with dark theme"
- "Create a tweet screenshot with light theme and show full text"
- "Check my twittershots API usage"
- "Get my API quota usage"

## Tool: get_screenshot

Get a screenshot image URL for a Twitter/X tweet.

**Parameters:**
- `url` (required): Twitter/X tweet URL or tweet ID
- `format` (optional): Image format - `svg` (default), `png`, or `html`
- `theme` (optional): Theme - `light` (default) or `dark`
- `logo` (optional): Logo type - `x` (default), `bluebird`, or `none`
- `showFullText` (optional): Show full tweet content (default: `true`)
- `showTimestamp` (optional): Show timestamp (default: `true`)
- `showViews` (optional): Show view count (default: `true`)
- `showStats` (optional): Show reply, retweet, and like counts (default: `true`)

**Example:**

```
use twittershots to screenshot https://x.com/elonmusk/status/2001742502332911922 in dark mode
```
Output: Screenshot URL with the generated image link

## Tool: get_usage

Get your current API quota usage, including remaining requests and total quota limit.

**Parameters:** None

**Example:**

```
check my twittershots API usage
```
or
```
get my API usage
```

**Output:**
```
API Usage:

Remaining: 1234
Limit: 2000
Used: 766 (38.3%)
```