Skip to main content
Glama
enesjakozh
The-Focus-AI

Buttondown MCP Server

by The-Focus-AI
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

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

Related MCP server: Buttondown MCP Server

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:

  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

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

  1. Start the server:

    pnpm mcp:start

  2. 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

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add some amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

License

ISC License - See LICENSE for details

Acknowledgments

Available Tools

4 tools
create_draftA

Create a new email draft in Buttondown with the specified content and optional title. This tool requires explicit user confirmation before proceeding as it will create a new draft in your Buttondown account.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesThe main content/body of the email draft
titleNoOptional title/subject for the email draft
confirmedYesMust be true to confirm the draft creation

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates that this is a write operation ('create a new draft'), specifies the target system ('in your Buttondown account'), and importantly discloses the confirmation requirement. However, it doesn't mention potential side effects, error conditions, or what happens to existing drafts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise with two sentences: the first states the core functionality, the second adds the critical behavioral constraint. Every word earns its place, and the most important information (the confirmation requirement) is appropriately front-loaded in the second sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a creation tool with no annotations and no output schema, the description does well by specifying the action, target system, and confirmation requirement. However, it doesn't describe what the tool returns (e.g., draft ID, success status) or potential error scenarios. Given the 100% schema coverage, the parameter documentation is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description mentions 'content and optional title' which aligns with the schema, but adds no additional semantic context beyond what the schema provides. The confirmation requirement is behavioral rather than parameter-specific.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Create a new email draft'), the target resource ('in Buttondown'), and the key components ('with the specified content and optional title'). It distinguishes this creation tool from sibling tools like get_analytics (read-only), list_emails (listing), and schedule_draft (scheduling).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'This tool requires explicit user confirmation before proceeding.' This creates a clear when-to-use condition (only when user confirmation is available) and implies when-not-to-use (without confirmation). While it doesn't name alternatives, the confirmation requirement serves as a strong usage constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_analyticsC

Retrieve analytics data for a specific email draft from Buttondown

ParametersJSON Schema
NameRequiredDescriptionDefault
draftIdYesThe ID of the email draft to get analytics for

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Retrieve analytics data' which implies a read-only operation, but doesn't specify what analytics are included (e.g., open rates, clicks), permissions required, rate limits, or response format. This is a significant gap for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it easy to understand at a glance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description is incomplete. It doesn't explain what analytics data is returned, potential errors, or behavioral traits. For a tool that retrieves data, this leaves critical gaps in understanding how to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the single parameter 'draftId' fully. The description adds no additional meaning beyond implying the parameter is for a specific email draft, which is redundant with the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Retrieve analytics data') and target resource ('for a specific email draft from Buttondown'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like 'list_emails' or 'schedule_draft', which might also involve analytics or draft operations, so it misses full sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a draft ID), exclusions, or how it differs from sibling tools like 'list_emails' that might list drafts. This leaves usage context unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_emailsB

List all emails, optionally filtered by status (draft, scheduled, sent)

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNoOptional status to filter emails by

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool lists emails with optional filtering, but doesn't cover critical aspects like whether this is a read-only operation, potential rate limits, authentication requirements, pagination behavior, or what the output format looks like. For a list tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with a single sentence that efficiently communicates the core functionality. Every word earns its place, and it's front-loaded with the main purpose. No wasted verbiage or unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a simple single-parameter tool, the description is incomplete. It doesn't address what the tool returns, how results are structured, whether there are limitations on the listing, or any behavioral aspects. For even a simple tool, more context about the operation would be helpful for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the single parameter 'status' fully documented in the schema including its enum values. The description adds minimal value beyond the schema by mentioning the optional status filtering, but doesn't provide additional context about parameter usage or implications. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('List') and resource ('emails'), and mentions optional filtering by status. However, it doesn't explicitly differentiate from sibling tools like 'get_analytics' which might also retrieve email data, leaving some ambiguity about when to choose this tool over others.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing emails with optional status filtering, but provides no explicit guidance on when to use this tool versus alternatives like 'get_analytics' or 'create_draft'. It mentions the filtering capability but doesn't specify scenarios or exclusions, leaving usage context to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

schedule_draftA

Schedule an existing email draft to be sent at a specific time. This tool requires explicit user confirmation before proceeding as it will modify the draft's status and schedule.

ParametersJSON Schema
NameRequiredDescriptionDefault
draftIdYesThe ID of the email draft to schedule
scheduledTimeYesWhen to send the email (ISO 8601 datetime format)
confirmedYesMust be true to confirm the scheduling

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it modifies the draft's status and schedule (indicating a mutation), requires user confirmation, and implies a time-based action. However, it lacks details on error handling, rate limits, or specific permissions needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences that are front-loaded and efficient. The first sentence states the purpose, and the second adds crucial behavioral context (confirmation requirement and modification effects), with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a mutation with user confirmation), no annotations, and no output schema, the description is somewhat complete but has gaps. It covers the action and confirmation need but lacks details on return values, error cases, or full behavioral context, making it adequate but not fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents all parameters (draftId, scheduledTime, confirmed). The description adds minimal value beyond the schema by implying the purpose of scheduling but does not provide additional syntax, format details, or usage examples for the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Schedule an existing email draft') and the resource ('email draft'), distinguishing it from sibling tools like create_draft (creation), get_analytics (analysis), and list_emails (listing). It specifies the outcome ('to be sent at a specific time') without being tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('Schedule an existing email draft') and includes a prerequisite ('requires explicit user confirmation'), but it does not explicitly state when not to use it or name alternatives among the sibling tools (e.g., when to use create_draft instead).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updates
    • First observedcreate_draft
    • First observedget_analytics
    • First observedlist_emails
    • First observedschedule_draft
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose targeting specific actions in the email lifecycle: create_draft for creation, list_emails for listing, get_analytics for analytics retrieval, and schedule_draft for scheduling. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case (create_draft, get_analytics, list_emails, schedule_draft). The verbs are appropriate and predictable, making the set easy to understand and use.

Tool Count4/5

With 4 tools, the count is reasonable for an email newsletter server, covering core operations. However, it feels slightly thin as it lacks tools for updating or deleting drafts, which are common in such domains, but the scope is still well-defined.

Completeness4/5

The tool set covers key email lifecycle stages: creation, listing, analytics, and scheduling. Minor gaps exist, such as no update_draft or delete_draft tools, but agents can work around this by creating new drafts or using existing ones, and the core workflow is supported.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers