# Memobird MCP Server

MCP server for [Memobird (咕咕机)](http://www.memobird.cn) thermal printer, based on [memobirdsdk](https://www.npmjs.com/package/memobirdsdk).

## Prerequisites

- Node.js >= 18
- Memobird Access Key (from [open.memobird.cn](http://open.memobird.cn))
- Memobird device ID (double-click device to print it out)

## Setup

```bash
npm install
npm run build
```

## Configuration

| Environment Variable | Required | Description |
|---|---|---|
| `MEMOBIRD_AK` | Yes | Access Key from open.memobird.cn |
| `MEMOBIRD_DEVICE_ID` | No | Device ID from `bind_user`, skip binding if set |
| `MEMOBIRD_USER_ID` | No | User ID from `bind_user`, skip binding if set |

## Usage

### Via npx (Recommended)

No local clone needed. Add the following config to use the published npm package directly.

**Claude Code** — add to `~/.claude/settings.json`:

First-time setup (only `MEMOBIRD_AK` needed, `bind_user` will be called automatically):

```json
{
  "mcpServers": {
    "memobird": {
      "command": "npx",
      "args": ["-y", "memobirdmcp"],
      "env": {
        "MEMOBIRD_AK": "your-access-key"
      }
    }
  }
}
```

After first binding, add the returned `userid` and `memobirdID` to skip `bind_user` in future sessions:

```json
{
  "mcpServers": {
    "memobird": {
      "command": "npx",
      "args": ["-y", "memobirdmcp"],
      "env": {
        "MEMOBIRD_AK": "your-access-key",
        "MEMOBIRD_DEVICE_ID": "your-device-id",
        "MEMOBIRD_USER_ID": "12345"
      }
    }
  }
}
```

**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), same env format as above.

### Via local build

If you prefer to run from source:

```json
{
  "mcpServers": {
    "memobird": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "MEMOBIRD_AK": "your-access-key"
      }
    }
  }
}
```

## Tools

### bind_user

Bind a user identifier to a Memobird device. **Must be called first if `MEMOBIRD_DEVICE_ID` and `MEMOBIRD_USER_ID` env vars are not set.** Returns a `userid` and `memobirdID` — save them to env vars to skip this step in future sessions.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `memobirdID` | string | Yes | Device ID (double-click the device to obtain) |
| `useridentifying` | string | Yes | Your unique user identifier |

### print_text

Print text content to the bound device. Supports Chinese characters (auto GBK encoding).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `text` | string | Yes | Text content to print |

### print_image

Print a monochrome bitmap image to the bound device. Use `convert_image` first to convert JPG/PNG.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `base64Image` | string | Yes | Monochrome bitmap as Base64 |

### print_from_url

Print content from a web URL to the bound device. Works best with static/server-rendered pages.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | Yes | URL to print |

### print_from_html

Print content from HTML source to the bound device. Use inline CSS and absolute image URLs.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `html` | string | Yes | HTML source code |

### get_print_status

Check the status of a submitted print job.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `printcontentid` | string | Yes | Print content ID from a print tool response |

Returns `printflag: 1` if printed successfully, `0` if pending/failed.

### convert_image

Convert a JPG/PNG image to monochrome bitmap format for printing. Use 384px width for best results.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `base64Image` | string | Yes | JPG or PNG image as Base64 |

## Typical Workflow

### First time

1. Call `bind_user` with your device ID and a user identifier
2. Save the returned `userid` and `memobirdID` to `MEMOBIRD_USER_ID` and `MEMOBIRD_DEVICE_ID` env vars in your MCP config
3. Use print tools as needed

### Subsequent sessions (env vars set)

1. Use `print_text` / `print_from_html` / `print_from_url` directly (no binding needed)
2. For images: call `convert_image` first, then `print_image` with the result
3. Optionally call `get_print_status` to check if printing completed

## License

ISC