# Dribbble MCP Server

MCP server that connects to the [Dribbble API v2](https://developer.dribbble.com/v2/) via OAuth, exposing tools for browsing shots, users, and design inspiration.

## Setup

### 1. Register a Dribbble App

1. Go to [dribbble.com/account/applications/new](https://dribbble.com/account/applications/new)
2. Fill in your app details:
   - **Name:** anything (e.g. "My MCP Server")
   - **Callback URL:** `http://localhost:3847/callback`
3. Note your **Client ID** and **Client Secret**

### 2. Configure Environment

```bash
cp .env.example .env
# Edit .env with your credentials
```

Or export directly:

```bash
export DRIBBBLE_CLIENT_ID="your_client_id"
export DRIBBBLE_CLIENT_SECRET="your_client_secret"
```

### 3. Install & Run

```bash
npm install
npm start
```

On first run, the server will open a browser URL for OAuth authorization. After you authorize, the token is saved to `~/.config/dribbble-mcp/tokens.json` and reused on subsequent runs.

## Tools

| Tool | Description |
|------|-------------|
| `get-shot` | Get a single shot by ID (images, designer, tags) |
| `get-shot-comments` | Get comments on a shot |
| `get-user` | Get a user profile by username |
| `get-user-shots` | Get shots by a specific user |
| `get-authenticated-user` | Get your own profile |
| `list-shots` | List public shots with pagination |
| `list-popular` | List popular shots |
| `list-debuts` | List debut shots (new designers) |
| `list-everyone` | List shots from everyone |
| `search-shots` | Search shots by keyword (client-side filter) |

## Configure MCP Clients

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "dribbble": {
      "command": "node",
      "args": ["--import", "tsx", "/absolute/path/to/dribble-mcp/src/index.ts"],
      "env": {
        "DRIBBBLE_CLIENT_ID": "your_client_id",
        "DRIBBBLE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

### Cursor

Settings > MCP > Add server:

```json
{
  "mcpServers": {
    "dribbble": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/dribble-mcp/src/index.ts"],
      "env": {
        "DRIBBBLE_CLIENT_ID": "your_client_id",
        "DRIBBBLE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

### Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector npx tsx src/index.ts
```

## OAuth Flow

1. First run starts a local callback server on `http://localhost:3847/callback`
2. Opens a Dribbble authorization URL in the terminal
3. You authorize the app in your browser
4. Dribbble redirects to the local server with an auth code
5. Code is exchanged for an access token and saved locally

## Project Structure

```
src/
├── index.ts          # Entry point
├── server.ts         # McpServer factory
├── config.ts         # Environment config
├── auth/
│   ├── oauth.ts      # OAuth flow + callback server
│   ├── token-store.ts # File-based token persistence
│   └── types.ts      # Auth types
├── api/
│   ├── client.ts     # Dribbble API client
│   └── types.ts      # API response types
└── tools/
    ├── shots.ts      # get-shot, get-shot-comments
    ├── users.ts      # get-user, get-user-shots
    └── browse.ts     # list-*, search-shots
```

## Notes

- **Scope:** `public` (read-only) — no write operations
- **Rate limit:** 60 requests/minute, 1,440/day per authenticated user
- **Token storage:** `~/.config/dribbble-mcp/tokens.json`
- **Search:** Dribbble v2 API has no native search endpoint; `search-shots` scans multiple pages and filters client-side

## License

MIT