npm package: @mercy34mercy/gyazo-mcp
Description: Model Context Protocol (MCP) server for Gyazo API integration - Upload images, list, retrieve, and manage your Gyazo screenshots
Author: mercy34mercy
Latest version: 1.0.0

# Gyazo MCP Server

A Model Context Protocol (MCP) server that integrates with the Gyazo API, enabling AI assistants to upload, list, retrieve, and manage images on Gyazo.

## Features

### Tools

- **upload_image** - Upload images to Gyazo
  - Base64 encoded image data
  - Optional title, description, collection ID, and referer URL
- **list_images** - List your uploaded images
  - Pagination support (page, per_page)
- **get_image** - Get detailed information about a specific image
  - Returns image metadata, OCR data if available
- **delete_image** - Delete an image from Gyazo
- **get_oembed** - Get oEmbed information for a Gyazo image URL

### Resources

- **gyazo://images** - Access your complete image list as a resource
- **gyazo://images/{image_id}** - Access specific image details as a resource

## Installation

### From npm (Recommended)

```bash
npm install -g @mercy34mercy/gyazo-mcp
```

### From source

```bash
git clone https://github.com/mercy34mercy/gyazo-remote-mcp.git
cd gyazo-remote-mcp
npm install
npm run build
```

## Configuration

### Get Your Gyazo Access Token

1. Visit [Gyazo OAuth Applications](https://gyazo.com/oauth/applications)
2. Create a new application or use an existing one
3. Copy your access token

## Usage

### Option 1: Local MCP (stdio)

This mode runs the MCP server locally and communicates via stdio.

#### With Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

**Using npx (Recommended)**
```json
{
  "mcpServers": {
    "gyazo": {
      "command": "npx",
      "args": ["-y", "@mercy34mercy/gyazo-mcp"],
      "env": {
        "GYAZO_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

**Using global installation**
```json
{
  "mcpServers": {
    "gyazo": {
      "command": "gyazo-mcp",
      "env": {
        "GYAZO_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

**Using source code**
```json
{
  "mcpServers": {
    "gyazo": {
      "command": "node",
      "args": ["/absolute/path/to/gyazo-remote-mcp/build/index.js"],
      "env": {
        "GYAZO_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

#### Standalone

```bash
GYAZO_ACCESS_TOKEN=your_token npm start
```

### Option 2: Remote MCP (HTTP/SSE)

This mode runs the MCP server as an HTTP service, suitable for deployment to Cloud Run, Railway, Render, etc.

#### Local Development

Start the HTTP server:

```bash
npm run start:http
```

The server will start on `http://localhost:3000` (or the PORT environment variable if set).

Then configure Claude Desktop to connect to your local server:

```json
{
  "mcpServers": {
    "gyazo": {
      "type": "http",
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer your_gyazo_token_here"
      }
    }
  }
}
```

#### Deploy to Google Cloud Run

1. **Set up Google Cloud Project**

```bash
gcloud config set project YOUR_PROJECT_ID
```

2. **Build and push Docker image**

```bash
gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/gyazo-mcp
```

3. **Deploy to Cloud Run**

```bash
gcloud run deploy gyazo-mcp \
  --image gcr.io/YOUR_PROJECT_ID/gyazo-mcp \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated
```

4. **Configure Claude Desktop for Remote MCP**

After deployment, you'll get a URL like `https://gyazo-mcp-xxxxx.run.app`. Add to your Claude Desktop config:

**Option A: Using Authorization Header (Recommended)**
```json
{
  "mcpServers": {
    "gyazo": {
      "type": "http",
      "url": "https://gyazo-mcp-xxxxx.run.app",
      "headers": {
        "Authorization": "Bearer your_gyazo_token_here"
      }
    }
  }
}
```

**Option B: Using Custom Header**
```json
{
  "mcpServers": {
    "gyazo": {
      "type": "http",
      "url": "https://gyazo-mcp-xxxxx.run.app",
      "headers": {
        "X-Gyazo-Token": "your_gyazo_token_here"
      }
    }
  }
}
```

**Option C: Using Query Parameter**
```json
{
  "mcpServers": {
    "gyazo": {
      "type": "http",
      "url": "https://gyazo-mcp-xxxxx.run.app?token=your_gyazo_token_here"
    }
  }
}
```

#### Deploy to Other Platforms

**Railway**
```bash
# Railway will automatically detect the Dockerfile
# No environment variables needed - token is passed from client
```

**Render**
```bash
# Create a new Web Service from the Render dashboard
# No environment variables needed - token is passed from client
```

#### Environment Variables

For Remote MCP deployment:
- `PORT` (optional): HTTP server port (default: 3000, Cloud Run uses 8080)
- `GYAZO_ACCESS_TOKEN`: **NOT required** - the access token is sent from the MCP client (Claude Desktop) in the request

For Local Development (HTTP mode):
- `GYAZO_ACCESS_TOKEN` (optional): Can be set for testing, but will be overridden by client request if provided

## Example Interactions

### Upload an Image

```
User: "Upload this screenshot to Gyazo"
Assistant: [Uses upload_image tool with base64 image data]
```

### List Recent Images

```
User: "Show me my recent Gyazo uploads"
Assistant: [Uses list_images tool]
```

### Get Image Details

```
User: "Get details for image ID abc123"
Assistant: [Uses get_image tool with image_id: "abc123"]
```

### Delete an Image

```
User: "Delete the image with ID abc123"
Assistant: [Uses delete_image tool]
```

## API Reference

### upload_image

**Input:**
```typescript
{
  imagedata: string;      // Base64 encoded image (required)
  title?: string;         // Image title
  desc?: string;          // Image description
  collection_id?: string; // Collection ID
  referer_url?: string;   // Referer URL
}
```

**Output:**
```json
{
  "image_id": "xxxxx",
  "permalink_url": "https://gyazo.com/xxxxx",
  "url": "https://i.gyazo.com/xxxxx.png",
  "thumb_url": "https://thumb.gyazo.com/thumb/xxxxx.png",
  "type": "png"
}
```

### list_images

**Input:**
```typescript
{
  page?: number;     // Page number (default: 1)
  per_page?: number; // Items per page (default: 20, max: 100)
}
```

**Output:**
```json
[
  {
    "image_id": "xxxxx",
    "permalink_url": "https://gyazo.com/xxxxx",
    "url": "https://i.gyazo.com/xxxxx.png",
    "created_at": "2025-01-01T00:00:00+0000",
    "metadata": { ... }
  }
]
```

### get_image

**Input:**
```typescript
{
  image_id: string; // Image ID (required)
}
```

**Output:**
```json
{
  "image_id": "xxxxx",
  "permalink_url": "https://gyazo.com/xxxxx",
  "url": "https://i.gyazo.com/xxxxx.png",
  "thumb_url": "https://thumb.gyazo.com/thumb/xxxxx.png",
  "type": "png",
  "created_at": "2025-01-01T00:00:00+0000",
  "metadata": { ... },
  "ocr": { ... }
}
```

### delete_image

**Input:**
```typescript
{
  image_id: string; // Image ID to delete (required)
}
```

**Output:**
```json
{
  "success": true,
  "image_id": "xxxxx",
  "type": "png",
  "message": "Image deleted successfully"
}
```

### get_oembed

**Input:**
```typescript
{
  url: string; // Gyazo image URL (required)
}
```

**Output:**
```json
{
  "type": "photo",
  "version": "1.0",
  "provider_name": "Gyazo",
  "provider_url": "https://gyazo.com",
  ...
}
```

## Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

## Project Structure

```
gyazo-mcp/
├── src/
│   ├── index.ts           # Entry point for stdio mode
│   ├── http-server.ts     # Entry point for HTTP/SSE mode
│   ├── server.ts          # MCP server implementation
│   └── gyazo-client.ts    # Gyazo API client
├── build/                 # Compiled JavaScript
├── Dockerfile             # Docker image for Cloud Run deployment
├── .dockerignore
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```

## Security

- Never commit your `.env` file or expose your access token
- Store your access token securely in environment variables
- Use `.gitignore` to exclude sensitive files

## Error Handling

All errors are returned in a consistent format:

```json
{
  "error": "ErrorName",
  "message": "Error description",
  "statusCode": 400
}
```

Common error types:
- **Authentication Error** - Invalid or missing access token
- **Not Found Error** - Image or resource not found
- **Validation Error** - Invalid parameters
- **Rate Limit Error** - API rate limit exceeded

## License

MIT

## Related Links

- [Gyazo API Documentation](https://gyazo.com/api/docs)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.