Buttondown MCP server

This TypeScript integration for the Buttondown newsletter service provides a user-friendly MCP server that allows you to manage newsletters, drafts, and analytics through the Model Context Protocol. It lets you integrate Buttondown's powerful newsletter capabilities with AI and large language model systems.

Installation

# Install using pnpm (recommended)
pnpm install

# Or using npm
npm install

# Or using yarn
yarn install

Configuration

Set up your API key using one of these methods:

1. Environment variable:

   export BUTTONDOWN_API_KEY=your_api_key
   

2. 1Password CLI (recommended):

   • Store your API key in 1Password at op://Development/Buttondown API/notesPlain
   • The integration will automatically fetch it when needed

Using the MCP Server

Starting the Server

# Start the MCP server
pnpm mcp:start

# Start with inspector (for development)
pnpm mcp:inspect

Available MCP Tools

The MCP server provides several tools for interacting with Buttondown:

List Emails

Lists all emails with optional status filtering.

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

Create Draft

Creates a new email draft.

{
  "content": "Email content in markdown",
  "title": "Optional email subject"
}

Get Analytics

Retrieves analytics for a specific email.

{
  "draftId": "email-id-here"
}

Schedule Draft

Schedules an email for sending.

{
  "draftId": "email-id-here",
  "scheduledTime": "2024-03-27T10:00:00Z"
}

CLI Interface

In addition to the MCP server, you can use the CLI interface for direct interaction:

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

Programmatic Usage

You can also integrate directly in your TypeScript code:

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);

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "buttondown" '{"command":"pnpm","args":["mcp:start"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "buttondown": {
            "command": "pnpm",
            "args": [
                "mcp:start"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "buttondown": {
            "command": "pnpm",
            "args": [
                "mcp:start"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect