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)

Related MCP server: MCPOSprint

Setup

npm install
npm run build

Configuration

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.

print_text

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

print_image

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

print_from_url

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

print_from_html

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

get_print_status

Check the status of a submitted print job.

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.

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