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)

npm install -g @mercy34mercy/gyazo-mcp

From source

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
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)

{
  "mcpServers": {
    "gyazo": {
      "command": "npx",
      "args": ["-y", "@mercy34mercy/gyazo-mcp"],
      "env": {
        "GYAZO_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Using global installation

{
  "mcpServers": {
    "gyazo": {
      "command": "gyazo-mcp",
      "env": {
        "GYAZO_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Using source code

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

Standalone

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:

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:

{
  "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

gcloud config set project YOUR_PROJECT_ID

2. Build and push Docker image

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

3. Deploy to Cloud Run

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)

{
  "mcpServers": {
    "gyazo": {
      "type": "http",
      "url": "https://gyazo-mcp-xxxxx.run.app",
      "headers": {
        "Authorization": "Bearer your_gyazo_token_here"
      }
    }
  }
}

Option B: Using Custom Header

{
  "mcpServers": {
    "gyazo": {
      "type": "http",
      "url": "https://gyazo-mcp-xxxxx.run.app",
      "headers": {
        "X-Gyazo-Token": "your_gyazo_token_here"
      }
    }
  }
}

Option C: Using Query Parameter

{
  "mcpServers": {
    "gyazo": {
      "type": "http",
      "url": "https://gyazo-mcp-xxxxx.run.app?token=your_gyazo_token_here"
    }
  }
}

Deploy to Other Platforms

Railway

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

Render

# 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:

{
  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:

{
  "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:

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

Output:

[
  {
    "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:

{
  image_id: string; // Image ID (required)
}

Output:

{
  "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:

{
  image_id: string; // Image ID to delete (required)
}

Output:

{
  "success": true,
  "image_id": "xxxxx",
  "type": "png",
  "message": "Image deleted successfully"
}

get_oembed

Input:

{
  url: string; // Gyazo image URL (required)
}

Output:

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

Development

Build

npm run build

Watch Mode

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:

{
  "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
• Model Context Protocol
• MCP TypeScript SDK

Contributing

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