Buttondown MCP

🚀 Buttondown API Integration

A comprehensive TypeScript implementation for integrating the Buttondown newsletter service, offering a Command Line Interface (CLI) and a Model Context Protocol (MCP) server to manage newsletters, drafts, and analytics.

🚀 Quick Start

This project is a TypeScript implementation designed to integrate with the Buttondown newsletter service. It provides a CLI and an MCP server, enabling users to manage newsletters, drafts, and analytics efficiently.

✨ Features

• Multiple Interfaces:
  • Command Line Interface (CLI) for direct interaction.
  • Model Context Protocol (MCP) server supporting AI/LLM integration.
  • Customizable TypeScript API for integration.
• Core Functions:
  • Newsletter draft management (create, update, delete).
  • Newsletter scheduling system.
  • Analytics data retrieval and formatting.
  • List management.
  • Tag management.
• Security:
  • 1Password integration for API key management.
  • Support for environment variables.
  • Secure credential handling.
• Developer Experience:
  • Full TypeScript support.
  • Comprehensive type definitions.
  • Types based on actual API responses.
  • Built - in testing tools.

📦 Installation

# Use pnpm (recommended)
pnpm install

# Or use npm
npm install

# Or use yarn
yarn install

📚 Documentation

Configuration

API keys can be provided in two ways:

1. Environment variables:

   export BUTTONDOWN_API_KEY=your_api_key
   

2. 1Password CLI (recommended):
   • Store the API key in op://Development/Buttondown API/notesPlain of 1Password.
   • The integration program will automatically retrieve it when needed.

Usage

Command Line Interface (CLI)

# List all emails
buttondown emails list

# Create a new draft
buttondown draft create <file>

# Schedule an email for sending
buttondown schedule set <draft - id> <relative time>

# Get analytics data
buttondown analytics get <draft - id>

MCP Server

1. Start the server:

   pnpm mcp:start
   

2. Start with debugging (for development):

   pnpm mcp:inspect
   

Available MCP tools:

• list_emails: List all emails with optional status filtering

  {
    "status": "draft" // Optional: "draft", "scheduled", "sending"
  }
  

• create_email: Create a new email draft

  {
    "subject": "string",
    "content": "string",
    "list_id": "string"
  }
  

Developer's Guide

The project structure is as follows:

src/
├── cli.ts - Implement the CLI interface
├── mcp - server.ts - Implement the MCP server
└── types.ts - Define types for interacting with the Buttondown API

Test command:

pnpm test

Development command:

pnpm dev

Contribution Guide

• Before submitting a pull request to the project, ensure that the code adheres to the project's coding standards.
• Submit issues or feature requests to the project's GitHub repository.

📄 License

• This project is licensed under the MIT License.

🙏 Acknowledgments

• Thanks to Buttondown for providing an excellent newsletter service.
• Thanks to [Model Context Protocol](https://github.com/cursor - ai/model - context - protocol) for providing the AI integration framework.