npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@bluefox-email/mcp

v0.4.0

Published

Local MCP server wrapping the bluefox.email public API as tools for AI agents (Claude Desktop, Claude Code).

Readme

bluefox.email MCP server

What this is: a small local program that lets an AI agent (Claude Desktop, Claude Code, Codex CLI, or any other MCP-compatible client) manage your bluefox.email account directly - creating campaigns, sending emails, managing contacts and subscriber lists, and more - just by you asking in plain language. No API docs, no writing code, no copy-pasting HTTP requests.

It runs on your own computer (not hosted anywhere), and only talks to bluefox.email using your own API key. It's published on npm as @bluefox-email/mcp, so your AI agent can run it with npx and you don't need to install anything first.

What it can do

Once connected, you can just ask your AI agent things like:

  • "Create a subscriber list called Newsletter."
  • "Set up a welcome email for new subscribers on that list."
  • "Create a campaign called Summer Sale, schedule it for tomorrow at 8am."
  • "How did my last campaign perform?"
  • "Add a new sending domain and check if it's verified yet."

See the full list of what's supported in Tools below.

Setup

1. Install Node.js

You need Node.js 20 or later. Your AI agent downloads and runs the server itself with npx (step 3 below), so you don't install anything else.

2. Get your credentials

You need two things from your bluefox.email account:

| What | Where to find it | |---|---| | Project ID | In the app: Project Settings > Integrations | | API key | In the app: Project Settings > API Keys & Domain Whitelist ("Get your API key") |

3. Connect it to your AI agent

Most MCP clients use the same config shape - a command to run plus the three env vars from step 2:

{
  "mcpServers": {
    "bluefox-email": {
      "command": "npx",
      "args": ["-y", "@bluefox-email/mcp@latest"],
      "env": {
        "BLUEFOX_BASE_URL": "https://api.bluefox.email",
        "BLUEFOX_PROJECT_ID": "YOUR_PROJECT_ID",
        "BLUEFOX_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

@latest makes your agent pick up new versions when it restarts. To stay on one version, pin it instead (for example @bluefox-email/[email protected]).

Windows: npx is a .cmd shim on Windows, and most MCP clients launch the server without a shell. That fails silently (spawn UNKNOWN). Use this command/args shape instead and keep everything else the same:

"command": "cmd",
"args": ["/c", "npx", "-y", "@bluefox-email/mcp@latest"],

Where that block goes, per client:

| Client | Put it in... | |---|---| | Claude Desktop | claude_desktop_config.json (Settings > Developer > Edit Config), then restart. | | Cursor | .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project), then reload. | | Windsurf | ~/.codeium/windsurf/mcp_config.json, then reload. | | Cline (VS Code extension) | Cline's "MCP Servers" panel > Configure MCP Servers - same block. |

Claude Code doesn't use a config file - run this in your terminal instead:

claude mcp add bluefox-email \
  --env BLUEFOX_BASE_URL=https://api.bluefox.email \
  --env BLUEFOX_PROJECT_ID=YOUR_PROJECT_ID \
  --env BLUEFOX_API_KEY=YOUR_API_KEY \
  -- npx -y @bluefox-email/mcp@latest

Windows: replace the last line with -- cmd /c npx -y @bluefox-email/mcp@latest (see the Windows note above).

Codex CLI also uses a single command instead of a config file:

codex mcp add bluefox-email \
  --env BLUEFOX_BASE_URL=https://api.bluefox.email \
  --env BLUEFOX_PROJECT_ID=YOUR_PROJECT_ID \
  --env BLUEFOX_API_KEY=YOUR_API_KEY \
  -- npx -y @bluefox-email/mcp@latest

Windows: replace the last line with -- cmd /c npx -y @bluefox-email/mcp@latest (see the Windows note above).

ChatGPT (the web/app chat product): as of now, ChatGPT's MCP support (Settings > Connectors) expects a server reachable at a URL, not a local command - so this local server can't be connected from ChatGPT directly. This is separate from Codex CLI above, which does support local stdio servers. If you want AI-agent access to bluefox.email from the ChatGPT web app specifically, use the REST API + OpenAPI spec instead (see your Project Settings > Integrations page in the app).

Once connected, start a new chat and ask it to do something with your bluefox.email project.

git clone https://github.com/bluefox-email/bluefox.email-mcp
cd bluefox.email-mcp
npm install

Then point your client at the local entry file:

{
  "mcpServers": {
    "bluefox-email": {
      "command": "node",
      "args": ["/absolute/path/to/bluefox.email-mcp/src/index.js"],
      "env": { "...": "as above" }
    }
  }
}

If the project ID or API key is missing or wrong, the server will fail to start with a clear error message instead of connecting in a broken state.

Tools

52 tools, grouped by area below. You can refer to things by name (a subscriber list, a campaign, a sender identity, ...) - the server looks up the matching id for you, you never need to know or pass raw ids yourself.

Emails (campaigns, transactional, triggered)

| Tool | What it does | |---|---| | create_campaign | Create a campaign email, optionally scheduling it. | | create_transactional_email | Create a reusable transactional email. | | send_transactional_email | Send a transactional email to one recipient. | | create_triggered_email | Create a triggered email for a subscriber list. | | send_triggered_email | Send a triggered email to a list (or specific recipients). | | update_email | Update a campaign/transactional/triggered email; also cancels/reschedules a campaign. | | get_email | Look up one email (with stats) or list all of a given type. | | get_email_recipients | Per-recipient detail for one send - who received/opened/clicked/bounced/unsubscribed, paginated. | | list_email_error_log | Send-processing and delivery errors for a campaign/transactional/triggered email, last 30 days. | | delete_email | Delete a campaign or triggered email. | | send_test_email | Send a one-off test send without affecting real stats. |

Contacts

| Tool | What it does | |---|---| | create_contact / get_contact / update_contact / delete_contact | Manage a single contact. | | list_contacts | List contacts, filtered by subscriber list (and status), saved segment, tags, and/or custom field values. | | import_contacts | Bulk-create (or subscribe) many contacts at once from a list of rows. | | bulk_update_contacts | Apply one action (delete, tag/untag, suppress, subscribe/unsubscribe) to many contacts by email. | | clean_contacts | Find (and optionally delete) contacts already suppressed for bounce or complaint. | | export_contacts | Export every contact on the project to a local CSV file. | | resend_verification_email | Resend the double opt-in confirmation email to a still-unverified list subscriber. |

Subscriber lists

| Tool | What it does | |---|---| | create_subscriber_list | Create a subscriber list, optionally with double opt-in. | | update_subscriber_list | Update a list's name/description/privacy/double opt-in. | | get_subscriber_list | Look up one list (with stats) or list all lists. | | delete_subscriber_list | Delete a subscriber list. | | list_list_subscribers | List the contacts subscribed to a list, with each one's per-list status. | | get_list_subscriber | Look up one contact's status on a specific list, by email. | | add_list_subscriber | Subscribe a contact to a list (creating the contact if needed). | | update_list_subscriber | Change a contact's status (unsubscribe/pause/resubscribe) or details on one list. |

Signup forms

| Tool | What it does | |---|---| | create_signup_form | Create a signup form (captcha, double opt-in, styling, target lists) that subscribes contacts to one or more lists. | | update_signup_form | Update a signup form's name, target lists, captcha, styling, double opt-in, or field settings. | | get_signup_form | Look up one signup form, or list every form on the project. | | delete_signup_form | Delete a signup form (existing subscriptions from it are kept). | | get_signup_form_embed_html | Generate the form's embeddable HTML and save it to a local file. |

Project settings and infrastructure

| Tool | What it does | |---|---| | manage_segment | List/create/get/update/delete segments (contact-property and engagement conditions). | | manage_project_settings | Get/update the project's name, logo, "unengaged contact" definition, auto-remove-on-bounce/complaint behavior, and domain whitelist. | | manage_design_system | Get the project's design system, or set/reset style overrides (colors, fonts, button/text/divider styles). | | manage_sending_setup | List/add/remove/check sending domains and sender identities. | | manage_webhook | Get/set/remove the project's webhook. | | test_webhook | Fire a synthetic event at the project's configured webhook URL to confirm it's reachable and signed correctly. | | manage_contact_fields_and_tags | Manage custom contact field definitions and contact tags. | | manage_suppression_list | List/add/remove entries on this project's suppression list. | | manage_templates | List/get/rename/delete templates, or create one by duplicating an existing template's content (metadata only - can't author template content from scratch, see Limitations). |

Production access and sending limits

| Tool | What it does | |---|---| | apply_for_production_access | Submit a production access request to move past sandbox limits on bluefox.email's shared infrastructure. | | get_production_access_status | Report production access status, domain verification, current limits/rates, and limit-increase history. | | request_limit_increase | Request a higher monthly sending limit (projects already on production access). | | get_sandbox_deliverability | Today's sandbox send count plus overall bounce/complaint rates. | | get_production_deliverability | Worst bounce/complaint rate over 7/30/90 days, per-domain breakdown, and this month's send count. | | export_domain_dns | Export a domain's required DNS records (DKIM, SPF, DMARC, MX) to a local CSV file. |

Bring-your-own AWS SES

| Tool | What it does | |---|---| | set_byo_aws_config | Submit or update the project's own AWS SES credentials (STS role or access key/secret). | | get_aws_config | Read back the currently configured BYO-AWS region, limit, sender identities, and credential hints. | | check_aws_credentials | Validate BYO-AWS credentials directly against SES. | | get_cloudformation_link | Get the CloudFormation quick-create link for the STS role bluefox.email needs. |

A well-behaved agent should ask you for details that matter (like a campaign's preview text) instead of guessing, and look up your real options (like your actual subscriber lists) instead of asking you for raw ids.

Limitations

  • No date-range filtering on list tools - "campaigns from this month" relies on the agent filtering the returned list itself, since the API only supports exact-match filters.
  • Visual editor (Chamaileon) content is uploaded as JSON (chamaileonJsonPath / chamaileonJson), either written by the agent or exported with chamaileonJsonOutputPath. An email can't be created straight from a saved template - export the template's JSON and upload that instead.
  • API keys can't be read or changed through this server - manage those from Project Settings in the app. (The domain whitelist can be changed, via manage_project_settings.)
  • Webhook secretKey must match one of the project's existing API keys, which this server can't look up for you - get it from Project Settings > API Keys & Domain Whitelist.

Development

npm test   # vitest + 100% coverage gate
npm run lint

Tests live next to the file they cover (src/tools/campaigns.js -> src/tools/campaigns.test.js, etc.), matching the sibling bluefox.email repos. Most test each tool's handler logic directly (mocked HTTP); src/tools/index.test.js spins up a real McpServer and Client over the SDK's in-memory transport to catch schema-registration issues the handler tests can't see.