Handwrytten Mcp Server

Handwrytten MCP Server

An MCP (Model Context Protocol) server that lets AI assistants like Claude send real handwritten notes through Handwrytten — robots with real pens writing your messages on physical cards, mailed to your recipients.

What can it do?

What can't it do!

Once connected, your AI assistant can:

• Send handwritten notes — single or bulk, with per-recipient customization
• Browse cards and fonts — discover available stationery templates and handwriting styles
• Manage addresses — save, update, and delete recipient and sender addresses
• Create custom cards — upload images, add logos and text, design your own cards
• Include gift cards and inserts — attach gift cards or marketing inserts to orders
• Manage QR codes — create and attach QR codes to custom cards
• Track orders — check order status, view history, get tracking info

Quick Start

Option A: Remote Server (OAuth — recommended)

The Handwrytten MCP server supports OAuth 2.0 authentication. Connect directly from Claude.ai, Claude Desktop, or Claude Code — no API key needed. You'll sign in with your Handwrytten account when prompted.

Claude.ai

Add Handwrytten from the MCP integrations menu — no installation required.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "handwrytten": {
      "url": "https://mcp.handwrytten.com/mcp"
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

claude mcp add handwrytten --transport http https://mcp.handwrytten.com/mcp

Option B: Local Server (API Key)

For development or self-hosted setups, you can run the server locally with an API key.

1. Sign up at handwrytten.com and get your API key from the API settings page.

1. Install and configure:

npm install -g @handwrytten/mcp-server

Claude Desktop (local)

{
  "mcpServers": {
    "handwrytten": {
      "command": "handwrytten-mcp",
      "env": {
        "HANDWRYTTEN_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code (local)

claude mcp add handwrytten -- env HANDWRYTTEN_API_KEY=your_api_key_here handwrytten-mcp

Start Using It

Just ask your AI assistant naturally:

> "Send a thank-you card to Jane Doe at 123 Main St, Phoenix, AZ 85001"

> "What cards do you have available for birthdays?"

> "Send handwritten notes to everyone in this CSV file"

Available Tools

Orders (Core)

| Tool | Description | |------|-------------| | send_order | Send a handwritten note — the primary tool. Supports single and bulk sends. | | get_order | Get order details including status and tracking | | list_orders | List orders with pagination |

Cards & Fonts

| Tool | Description | |------|-------------| | list_cards | Browse all available card/stationery templates | | get_card | Get details of a specific card | | list_card_categories | Get card categories (Thank You, Birthday, etc.) | | list_fonts | Browse handwriting styles for orders | | list_customizer_fonts | Browse printed fonts for custom card text zones |

Address Book

| Tool | Description | |------|-------------| | list_recipients | List saved recipient addresses | | add_recipient | Save a new recipient address | | update_recipient | Update an existing recipient | | delete_recipient | Delete recipient address(es) | | list_senders | List saved sender (return) addresses | | add_sender | Save a new sender address | | delete_sender | Delete sender address(es) | | list_countries | Get supported countries | | list_states | Get states/provinces for a country |

Gift Cards & Inserts

| Tool | Description | |------|-------------| | list_gift_cards | Browse gift card products with denominations | | list_inserts | Browse card inserts (business cards, flyers) |

Custom Cards

| Tool | Description | |------|-------------| | list_custom_card_dimensions | Get available card dimensions | | upload_custom_image | Upload a cover or logo image | | check_custom_image | Check image quality requirements | | list_custom_images | List uploaded images | | delete_custom_image | Delete an uploaded image | | create_custom_card | Create a custom card design | | get_custom_card | Get custom card details | | delete_custom_card | Delete a custom card |

QR Codes

| Tool | Description | |------|-------------| | list_qr_codes | List account QR codes | | create_qr_code | Create a new QR code | | delete_qr_code | Delete a QR code | | list_qr_code_frames | Browse decorative QR code frames |

Basket (Advanced)

| Tool | Description | |------|-------------| | basket_add_order | Add an order to the basket | | basket_send | Submit the basket for processing | | basket_list | List items in the basket | | basket_count | Count basket items | | basket_remove | Remove a basket item | | basket_clear | Clear the basket | | list_past_baskets | List previously submitted baskets |

Account

| Tool | Description | |------|-------------| | get_user | Get account profile and credits balance | | list_signatures | List saved handwriting signatures |

Example Conversations

Simple send: > You: "Send a thank-you note to John Smith at 456 Oak Ave, Tempe AZ 85281 from our company" > Claude: calls listcards → listfonts → send_order

Bulk send: > You: "Send birthday cards to all these people: [list/CSV]" > Claude: calls listcards → listfonts → send_order with array of recipients

Custom card: > You: "Create a custom card with our company logo and send it to our top 5 clients" > Claude: calls uploadcustomimage → createcustomcard → listrecipients → sendorder

Development

git clone https://github.com/handwrytten/handwrytten-mcp-server
cd handwrytten-mcp-server
npm install
npm run build

Test locally in stdio mode (API key auth):

HANDWRYTTEN_API_KEY=your_key node dist/index.js

Run the HTTP server with OAuth (requires OAuth client credentials):

MCP_SERVER_URL=http://localhost:3000 \
OAUTH_CLIENT_ID=your_client_id \
OAUTH_CLIENT_SECRET=your_client_secret \
node dist/index.js

Built On

• Handwrytten TypeScript SDK — the official SDK this server wraps
• Model Context Protocol SDK — the MCP framework

Privacy & Support

• Privacy Policy: handwrytten.com/privacy-policy
• Support: handwrytten.com/contact or email mcp@handwrytten.com

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: handwrytten
• Source: handwrytten/mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.