@cloudwerxlab/base64-mcp/README.md

MCP server that converts base64 images and image URLs into markdown for display in chat

# Base64MCP

This is a Model Context Protocol (MCP) server that provides tools to convert base64-encoded images and image URLs into markdown-formatted image embeds for display in LLM chat interfaces (e.g., OpenWebUI chat).

## Tools

- **base64-to-url**: Accepts base64-encoded image data (optionally prefixed with data URI), saves it as an image file, and returns a markdown snippet with a URL to display the image.
- **display-url**: Accepts an image URL and returns a markdown snippet to display the image.

## Usage

1. Install dependencies:
   ```bash
   npm install
   ```

2. Start the MCP server:
   ```bash
   npm start
   ```

3. MCP endpoint:

   - POST requests: `http://localhost:4000/mcp`
   - Static images served at: `http://localhost:4000/images/`

## Tool Integration

Clients (e.g., OpenWebUI chat) should always use the `base64-to-url` tool when they have base64-encoded image data, and the `display-url` tool when they have a direct image URL. The server will return a markdown snippet for the client to render as an image.

## Example Cursor JSON

Here is an example of how an LLM client (e.g., Cursor) can invoke the `base64-to-url` tool to upload base64 image data:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "base64-to-url",
  "params": {
    "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
  }
}
```

To display an existing image URL using the `display-url` tool:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "display-url",
  "params": {
    "url": "https://example.com/path/to/image.jpg"
  }
}
```

## Example mcpservers.json

Clients that support loading servers from a `mcpservers.json` file (e.g., Cursor) can register this server with an entry like:

```json
{
  "mcpServers": {
    "base64-mcp": {
      "command": "npx",
      "args": ["-y", "@cloudwerxlab/base64-mcp"],
      "env": {
        "BASE_URL": "http://localhost:4000"
      }
    }
  }
}
```

Adjust the server name, package name, and `BASE_URL` as needed based on your environment.