Snap.as MCP Server

A Model Context Protocol (MCP) server for uploading photos to Snap.as using Write.as authentication.

Features

• Upload JPG, PNG, or GIF images (max 10MB) to Snap.as
• Automatic Write.as authentication with short-lived access tokens
• Returns public URLs for uploaded photos
• Configurable response formats (Markdown or JSON)
• Comprehensive error handling with actionable messages

Installation

NPX Usage (Recommended)

No installation required! Use directly with npx:

npx snapas-mcp-server

Local Installation

npm install -g snapas-mcp-server

Configuration

The server requires Write.as credentials for authentication. Set these environment variables:

export WRITEAS_USERNAME="your-username"
export WRITEAS_PASSWORD="your-password"

Security Note: Access tokens are short-lived and obtained automatically on each request. Never store or configure access tokens directly.

Usage

As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "snapas": {
      "command": "npx",
      "args": ["snapas-mcp-server"],
      "env": {
        "WRITEAS_USERNAME": "your-username",
        "WRITEAS_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

snapas_upload_photo

Upload an image file to Snap.as and receive a public URL.

Parameters:

• file_path (string, required): Absolute path to the image file
• username (string, optional): Write.as username (overrides env variable)
• password (string, optional): Write.as password (overrides env variable)
• response_format (string, optional): Output format - "json" (default) or "markdown"

Example Usage:

// Via MCP tool call (default JSON response)
{
  "file_path": "/Users/username/photos/sunset.jpg"
}

Response (JSON format - default):

{
  "id": "abc123",
  "filename": "sunset.jpg",
  "size": 245760,
  "url": "https://i.snap.as/abc123.jpg"
}

Response (Markdown format):

// Via MCP tool call with markdown response
{
  "file_path": "/Users/username/photos/sunset.jpg",
  "response_format": "markdown"
}

## Photo Uploaded Successfully

**URL:** https://i.snap.as/abc123.jpg
**ID:** abc123
**Filename:** sunset.jpg
**Size:** 240.00 KB

You can access the photo at: https://i.snap.as/abc123.jpg

Supported File Types

• JPG/JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)

Maximum file size: 10MB

Error Handling

The server provides clear, actionable error messages:

• Authentication failed: Invalid Write.as credentials (HTTP 401)
• File not found: The specified file path doesn't exist
• Unsupported file type: File must be JPG, PNG, or GIF
• File exceeds 10MB limit: File is too large
• Rate limit exceeded: Too many requests (HTTP 429)
• Access denied: Insufficient permissions (HTTP 403)

Development

Prerequisites

• Node.js >= 18
• npm

Setup

# Clone the repository
git clone https://github.com/rawveg/snapas-mcp
cd snapas-mcp-server

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Test locally
npm start

Testing

The project uses Vitest with comprehensive test coverage:

# Run tests once
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Project Structure

snapas-mcp-server/
├── src/
│   ├── __tests__/          # Test files
│   │   ├── services/
│   │   └── utils/
│   ├── services/           # API clients
│   │   ├── snapas-client.ts
│   │   └── writeas-client.ts
│   ├── utils/              # Utilities
│   │   ├── auth.ts
│   │   └── file-handler.ts
│   ├── constants.ts        # Configuration constants
│   ├── index.ts            # MCP server entry point
│   ├── schemas.ts          # Zod validation schemas
│   └── types.ts            # TypeScript types
├── package.json
├── tsconfig.json
└── vitest.config.ts

API References

• Snap.as API Documentation
• Write.as API Documentation
• Model Context Protocol

License

AGPL-3.0-or-later

Contributing

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