Buttondown MCP Server

Buttondown API Integration

A comprehensive TypeScript integration for the Buttondown newsletter service, providing both a CLI interface and a Model Context Protocol (MCP) server for managing newsletters, drafts, and analytics.

Features

Multiple Interfaces:
- Command Line Interface (CLI) for direct interaction
- Model Context Protocol (MCP) server for AI/LLM integration
- Programmatic TypeScript API for custom integrations
Core Functionality:
- Email draft management (create, update, delete)
- Email scheduling system
- Analytics retrieval and formatting
- List management
- Tag management
Security:
- 1Password integration for API key management
- Environment variable support
- Secure credential handling
Developer Experience:
- Full TypeScript support
- Comprehensive type definitions
- Real API response-based types
- Built-in testing utilities

Installation

# Install using pnpm (recommended)
pnpm install

# Or using npm
npm install

# Or using yarn
yarn install

Configuration

The API key can be provided in two ways:

Environment variable:
export BUTTONDOWN_API_KEY=your_api_key
1Password CLI (recommended):
- Store your API key in 1Password at op://Development/Buttondown API/notesPlain
- The integration will automatically fetch it when needed

Usage

CLI Interface

# List all emails
buttondown emails list

# Create a new draft
buttondown draft create <file>

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

# Get analytics
buttondown analytics get <draft-id>

MCP Server

Start the server:
pnpm mcp:start
Start with inspector (for development):
pnpm mcp:inspect

Available MCP tools:

list_emails: List all emails with optional status filtering
{ "status": "draft" // Optional: "draft", "scheduled", "sent" }
create_draft: Create a new email draft
{ "content": "Email content in markdown", "title": "Optional email subject" }
get_analytics: Get analytics for a specific email
{ "draftId": "email-id-here" }
schedule_draft: Schedule an email for sending
{ "draftId": "email-id-here", "scheduledTime": "2024-03-27T10:00:00Z" }

Programmatic Usage

import { ButtondownAPI } from "api-integrator";

// Initialize the client
const api = new ButtondownAPI(); // Will use 1Password or env var

// List drafts
const drafts = await api.getDrafts();

// Create a draft
const draft = await api.createEmail({
  subject: "My Newsletter",
  body: "Content here",
  status: "draft",
});

// Schedule an email
const scheduled = await api.scheduleEmail(draft.id, "2024-03-27T10:00:00Z");

// Get analytics
const analytics = await api.getEmailStats(draft.id);

Development

# Build the project
pnpm build

# Run tests
pnpm test

# Start MCP server in development mode
pnpm mcp:inspect

# Build MCP server
pnpm mcp:build

Testing

The project includes several types of tests:

Unit tests for core functionality
Integration tests for API interactions
CLI command tests
MCP server tests

Run tests with:

pnpm test

Project Structure

.
├── src/
│   ├── api/          # Core API client
│   ├── cli/          # CLI implementation
│   ├── mcp/          # MCP server
│   ├── types/        # TypeScript definitions
│   └── utils/        # Shared utilities
├── tests/            # Test files
├── api-responses/    # Cached API responses
└── memory-bank/      # Project documentation

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

ISC License - See LICENSE for details

Acknowledgments

Buttondown for their excellent newsletter service
Model Context Protocol for the AI integration framework

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI and LLM systems to interact with the Buttondown newsletter service, supporting email drafting, scheduling, analytics retrieval, and list management through a Model Context Protocol interface.

Related MCP Servers

Gmail MCP Server
zacco16
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to interact with Gmail services, supporting email operations, draft management, and calendar functionality through Google API integration.
Last updated -
TypeScript
Mail MCP Tool
shuakami
A
security
F
license
A
quality
An MCP-based email tool that enables AI models to access email services through standardized interfaces, allowing AI assistants to perform various email operations like sending emails, reading inboxes, and handling attachments.
Last updated -
17
16
TypeScript
Enhanced Gmail MCP Server
theposch
-
security
A
license
-
quality
A Model Context Protocol server that enables AI assistants like Claude to interact with Gmail through natural language, providing comprehensive email management capabilities including sending, reading, organizing, searching, and managing drafts and labels.
Last updated -
Python
GPL 3.0
IMAP MCP Server
non-dirty
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to access and manage email through IMAP, supporting browsing, searching, reading, and organizing emails while learning user preferences over time.
Last updated -
2
Python

View all related MCP servers