Memobird MCP Server

MCP server for Memobird (咕咕机) thermal printer, based on memobirdsdk.

Prerequisites

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

Setup

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

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

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

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