# postscript-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

MCP server for [Postscript](https://postscript.io), the SMS marketing platform for Shopify e-commerce stores. 5 tools for AI copywriting and marketing agents to query subscribers, look up opt-in keyword IDs, add new subscribers (with proper consent flow), list active SMS campaigns, and check audience segment sizes before drafting SMS blasts.

As of May 2026, Postscript does not have an official MCP server. The community attempt is a zero-star placeholder. This is the production-quality rail to fill that gap.

## The 5 tools

| Tool | Purpose |
|---|---|
| `list_subscribers` | Query the active SMS subscriber list |
| `get_keyword_id` | Look up SMS opt-in keyword IDs (required for compliant subscriber creation) |
| `add_subscriber` | Add a new phone number to a list, tied to a documented consent flow |
| `list_campaigns` | Retrieve recent SMS campaigns and their deployment status |
| `check_segment_size` | Look up audience segments and their subscriber counts |

## Install

```bash
pip install postscript-mcp
```

## Configure

```bash
export POSTSCRIPT_API_KEY="your-postscript-private-api-key"
```

Get a Postscript Private API Key in your Postscript dashboard under **Apps -> API**. The key is sent as a Bearer token; vault it server-side only.

## Use with Claude Desktop

```json
{
  "mcpServers": {
    "postscript": {
      "command": "postscript-mcp",
      "env": {
        "POSTSCRIPT_API_KEY": "your-postscript-private-api-key"
      }
    }
  }
}
```

Restart Claude Desktop. The 5 Postscript tools are now available.

## Use case: AI SMS marketing assistant

Typical agent flow:

1. Call `check_segment_size()` to see which audience segments exist and how many subscribers each contains. Pick the right one for the campaign.
2. Call `list_campaigns()` to see what has already been sent and avoid sending a duplicate.
3. (For subscriber growth flows) Call `get_keyword_id()` to find the consent-flow keyword for the right list, then `add_subscriber(phone_number, keyword_id)` to add a new opt-in.
4. Drafting an SMS: use the segment + subscriber data to scope the message correctly before passing it to a downstream SMS-send tool (Postscript send endpoints are intentionally NOT in this MCP to keep the rail safe).

## Compliance note

SMS subscriber creation is regulated under TCPA (US) and CTIA carrier requirements. The `add_subscriber` tool always requires a `keyword_id`, which ties every new subscription to a documented consent flow you previously configured in Postscript. This MCP does not provide a way to add subscribers without a keyword_id. Do not attempt to bypass this; non-consented subscribers are a compliance and legal risk for the merchant.

## Architecture

- Public MIT-licensed wrapper around the Postscript REST API v2
- Async HTTP via `httpx`
- pydantic v2 input validation
- Bearer token auth, server-side only
- Rate-limit aware (429 returns a clean error)

## Development

```bash
git clone https://github.com/NoBanks/postscript-mcp.git
cd postscript-mcp
pip install -e ".[dev]"
pytest
```

## License

MIT. See [LICENSE](LICENSE).

## Author

Ryan Hammer (NoBanks). Solo founder + engineer. Built this and 10 other MCP servers as part of a sprint to expose AI agent rails for the products and platforms shipping daily.

- GitHub: [@NoBanks](https://github.com/NoBanks)
- X/Twitter: [@livingagentic](https://x.com/livingagentic)
- Site: [livingagentic.me](https://livingagentic.me), [nohumannearby.com](https://nohumannearby.com)

Open to AI engineering roles, contract or full-time, remote-only.