# Handwrytten Mcp Server

> Handwrytten's MCP server

- **Type:** MCP server
- **Install:** `agentstack add mcp-handwrytten-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [handwrytten](https://agentstack.voostack.com/s/handwrytten)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [handwrytten](https://github.com/handwrytten)
- **Source:** https://github.com/handwrytten/mcp-server

## Install

```sh
agentstack add mcp-handwrytten-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Handwrytten MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets AI assistants like Claude send real handwritten notes through [Handwrytten](https://www.handwrytten.com) — 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`:

```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

```bash
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](https://www.handwrytten.com) and get your API key from the [API settings page](https://www.handwrytten.com/api/).

2. Install and configure:

```bash
npm install -g @handwrytten/mcp-server
```

#### Claude Desktop (local)

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

#### Claude Code (local)

```bash
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 list_cards → list_fonts → send_order*

**Bulk send:**
> You: "Send birthday cards to all these people: [list/CSV]"
> Claude: *calls list_cards → list_fonts → 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 upload_custom_image → create_custom_card → list_recipients → send_order*

## Development

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

```bash
HANDWRYTTEN_API_KEY=your_key node dist/index.js
```

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

```bash
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](https://www.npmjs.com/package/handwrytten) — the official SDK this server wraps
- [Model Context Protocol SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk) — the MCP framework

## Privacy & Support

- **Privacy Policy**: [handwrytten.com/privacy-policy](https://www.handwrytten.com/privacy-policy)
- **Support**: [handwrytten.com/contact](https://www.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](https://github.com/handwrytten)
- **Source:** [handwrytten/mcp-server](https://github.com/handwrytten/mcp-server)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-handwrytten-mcp-server
- Seller: https://agentstack.voostack.com/s/handwrytten
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.