Missive MCP Server + CLI

A Model Context Protocol (MCP) server and CLI that expose the Missive REST API as tools for AI assistants and agents.

• missive-cli — Command-line interface for AI agents, scripting, and automation ✅ recommended
• missive-mcp — MCP server for clients that cannot run shell commands

Prerequisites

• Node.js v24 or later
• A Missive account on the Productive plan
• A Missive API token — go to Missive → Preferences → API

MCP Server Setup

Step 1 — Install

npm install -g missive-mcp

Or run without installing (one-off / CI):

npx missive-mcp
npx missive-cli conversations list --params '{"inbox":true}'

Verify:

missive-mcp --help
missive-cli --help

Step 2 — Configure your client

Claude Code

claude mcp add missive \
  -e MISSIVE_API_TOKEN=your_token_here \
  -e MISSIVE_TOOLS=conversations,drafts,contacts,responses,messages,organizations \
  -e MISSIVE_ACTIONS=read,write \
  -- missive-mcp

Verify:

claude mcp list

Claude Desktop

Edit the config file:

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

{
  "mcpServers": {
    "missive": {
      "command": "missive-mcp",
      "env": {
        "MISSIVE_API_TOKEN": "your_token_here",
        "MISSIVE_TOOLS": "conversations,drafts,contacts,responses,messages,organizations",
        "MISSIVE_ACTIONS": "read,write"
      }
    }
  }
}

Restart Claude Desktop after saving.

CLI Setup

Install

npm install -g missive-mcp

# Now available as:
missive-cli --help

Or run without installing:

npx missive-cli conversations list --params '{"inbox":true}'

Configure

# Set your API token (stored in ~/.config/missive-cli/config.json)
missive-cli config set token your_api_token_here

# Enable tool groups (at least one required)
missive-cli config set tools conversations,drafts,contacts,responses,messages,organizations

# Enable actions (at least one required)
missive-cli config set actions read,write

# Check current config
missive-cli config get

Or use environment variables per-invocation:

MISSIVE_API_TOKEN=xxx MISSIVE_TOOLS=conversations MISSIVE_ACTIONS=read \
  missive-cli conversations list --params '{"inbox":true}'

CLI Usage

# List inbox conversations
missive-cli conversations list --params '{"inbox":true,"limit":10}'

# Agent-friendly summary output (id, subject, status, assignees, labels)
missive-cli conversations list --params '{"inbox":true}' --format summary

# Get a conversation
missive-cli conversations get --params '{"id":"abc123"}'

# List messages in a conversation
missive-cli conversations messages list --params '{"id":"abc123"}'

# Slim message view — strips HTML and quoted email blocks automatically
missive-cli conversations messages list --params '{"id":"abc123"}' --format slim

# Cap long messages to save context tokens
missive-cli conversations messages list --params '{"id":"abc123"}' --format slim --truncate 800

# Save full message body to a file instead
missive-cli conversations messages list --params '{"id":"abc123"}' --format slim --save-body /tmp/msg.txt

# Reply to a conversation thread (auto-populates recipients and quoting)
missive-cli conversations reply-draft \
  --params '{"id":"abc123"}' \
  --json '{"body":"<p>Your reply.</p>","account":"<account_id>"}'

# Compose a draft
missive-cli drafts create --json '{"body":"Hello","to_fields":[{"address":"[email protected]"}]}'

# Send immediately (requires actions=read,write,send)
missive-cli drafts create --json '{"body":"Hello","to_fields":[{"address":"[email protected]"}],"send":true}'

# Preview a request without executing it
missive-cli conversations list --params '{"inbox":true}' --dry-run

# Paginate all results as NDJSON (one item per line)
missive-cli conversations list --params '{"inbox":true}' --page-all

# Inspect the schema for any command
missive-cli schema drafts create

Available Tools (27)

| Group | Tools | |-------|-------| | Analytics | missive_create_analytics_report, missive_get_analytics_report | | Contacts | missive_create_contacts, missive_update_contacts, missive_list_contacts, missive_get_contact | | Contact Books | missive_list_contact_books | | Contact Groups | missive_list_contact_groups | | Conversations | missive_list_conversations, missive_get_conversation, missive_list_conversation_messages, missive_list_conversation_comments, missive_list_conversation_drafts, missive_list_conversation_posts, missive_merge_conversations | | Drafts | missive_create_draft, missive_create_reply_draft, missive_delete_draft | | Messages | missive_create_message, missive_get_messages, missive_list_messages_by_email_id | | Organizations | missive_list_organizations | | Responses | missive_list_responses, missive_get_response, missive_create_responses, missive_update_responses, missive_delete_responses |

Scope Configuration

Both missive-mcp and missive-cli default to no tools and no actions — every capability must be explicitly enabled. This prevents accidental writes or deletes.

MISSIVE_TOOLS

Comma-separated list of tool groups to enable: analytics, contacts, contact_books, contact_groups, conversations, drafts, messages, organizations, responses

MISSIVE_ACTIONS

Comma-separated list of permitted actions: read, write, delete, send

CLI scope: env var + config file

When using missive-cli, setting both MISSIVE_TOOLS/MISSIVE_ACTIONS and the config file causes the effective scope to be their intersection — not the env var alone. The env var acts as a ceiling (e.g. an operator restricts to MISSIVE_TOOLS=conversations) and the config file can further narrow it, but cannot grant groups not in the env var. If the two sets have no overlap, startup fails with a clear error.

Suggested Configs

Sales — compose drafts, manage contacts, browse conversations

Claude will compose drafts but will not send them unless send is in MISSIVE_ACTIONS. Always review a draft in Missive before sending.

{
  "MISSIVE_TOOLS": "conversations,contacts,contact_books,contact_groups,drafts,responses,messages",
  "MISSIVE_ACTIONS": "read,write"
}

| Capability | Included | |-----------|----------| | Read conversations & messages | ✅ | | Search & manage contacts | ✅ | | Compose email drafts | ✅ | | Use saved reply templates | ✅ | | Send emails | ❌ | | Delete drafts / responses | ❌ | | Analytics reports | ❌ |

Read-only — safe browsing and reporting

{
  "MISSIVE_ACTIONS": "read"
}

For AI Agents

See INSTALL.md for a step-by-step agent integration guide covering both modes:

• Mode A: CLI ✅ recommended — missive-cli via Bash, portable across any agent, auditable, scriptable
• Mode B: MCP — native tools via MCP protocol, for clients that cannot run shell commands

Skills (Mode B)

skills/missive/ contains machine-readable skill files for agents using missive-cli:

| File | Contents | |------|----------| | SKILL.md | Entry point — invariants, quick reference, setup, error handling | | conversations.md | Browse inbox, read threads, search, merge | | drafts.md | Compose, send, schedule, delete drafts | | contacts.md | Search, read, create, update contacts | | responses.md | Manage saved reply templates | | analytics.md | Create and poll analytics reports | | messages.md | Fetch raw messages, post to custom channels |

npx skills add oursky/missive-mcp --skill missive

Local Development

Running locally

# Install deps, build, and restore installed skills
make build
npx skills experimental_install

# Run MCP server directly (no build needed, uses tsx)
npm run dev

# Run CLI directly
npm run dev:cli -- conversations list --params '{"inbox":true}'

Testing

make test                                        # unit tests
make test-watch                                  # unit tests in watch mode
make test-integration MISSIVE_API_TOKEN=xxx      # integration tests against real API (add [email protected] to also run the send-email test)
make ci                                          # full local CI: lint + typecheck + audit + build + test

Integration tests are read-safe by default (no emails sent, no data permanently deleted). They create and immediately delete a draft and a response template to verify write operations.

CI/CD

GitHub Actions runs automatically on every push and pull request:

• ci job — runs make ci (lint → typecheck → audit → build → test) on all pushes and PRs to main
• integration job — runs make test-integration on pushes to main only, requires MISSIVE_API_TOKEN secret

To run the full CI suite locally before pushing:

make ci

Deployment

This server runs as a local process launched by the MCP client — there is no server to deploy. Each user runs it on their own machine.

Keeping up to date

npm install -g missive-mcp
# Restart Claude Desktop or reload Claude Code after updating