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

Deploy Server

HTTP connection URL

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

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.

Tools

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

ClickUp MCP Server
v4lheru
A
security
A
license
A
quality
An enhanced Model Context Protocol server that enables AI assistants to interact with ClickUp workspaces, supporting task relationships, comments, checklists, and workspace management through natural language.
Last updated -
2
2
MIT License
ClickUp MCP Server
windalfin
-
security
A
license
-
quality
A Model Context Protocol server that enables AI agents to interact with ClickUp workspaces, allowing task creation, management, and workspace organization through natural language commands.
Last updated -
1,905
2
MIT License
Linear MCP Integration Server
skspade
-
security
F
license
-
quality
Enables AI models to interact with Linear for issue tracking and project management through the Model Context Protocol, supporting capabilities like creating issues, searching, managing sprints, and bulk updating statuses.
Last updated -
5
LinkedIn MCP Server
felipfr
A
security
A
license
A
quality
Enables AI assistants to interact with LinkedIn data through the Model Context Protocol, allowing profile searches, job discovery, messaging, and network analytics.
Last updated -
28
49
15
MIT License

View all related MCP servers

Buttondown MCP Server