subscriber-analyzer

An MCP (Model Context Protocol) server that analyzes subscriber CSV exports — giving you instant domain intelligence: who's reading from Red Hat vs. Google vs. the DoD vs. MIT, which readers route through RSS bridges, and which addresses hint at job titles or notable roles.

Built for Buttondown exports first, but works with any CSV that has an email column.

What it does

Point it at a subscriber CSV and it gives you:

Domain counts — ranked from most to least common
Categorized breakdown — consumer (Gmail, iCloud, etc.), corporate, government, education, RSS readers/aggregators
Industry verticals — corporate subscribers grouped by market segment (cloud & infra, DevOps & observability, fintech, consulting, etc.)
Audience intelligence — role/title signals in email addresses, professional domain share, org depth, and sophistication metrics formatted for sponsors
Notable subscriber detection — government agencies, universities, recognizable tech companies, and addresses with role/title hints (cto, sre, devops, architect, etc.)
Styled HTML report — a self-contained, shareable sponsor report generated from live data

Tools exposed via MCP

| Tool | What it does | |---|---| | analyze_subscribers | Full analysis — returns JSON, plain-text, or a styled HTML report | | list_domains | Filtered domain list by category (corporate, government, education, etc.) | | find_notable_emails | Notable addresses filtered by type (notable-org, government, role-title, etc.) |

Quick start

1. Install

git clone https://github.com/chrisshort/subscriber-analyzer.git
cd subscriber-analyzer
npm install
npm run build

2. Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "subscriber-analyzer": {
      "command": "node",
      "args": ["/absolute/path/to/subscriber-analyzer/dist/index.js"]
    }
  }
}

Restart Claude Desktop. The three tools will appear automatically.

3. Use it

Ask Claude natural questions:

"Analyze my subscriber CSV at ~/Downloads/subscribers.csv and tell me which corporate domains have the most readers."

"Generate a sponsor report from ~/Downloads/subscribers.csv and save it to ~/Desktop/report.html"

"Find all government email addresses in ~/subscribers.csv"

"What percentage of my subscribers use consumer email providers?"

Generating the HTML sponsor report

The analyze_subscribers tool supports an html format that produces a fully styled, self-contained report — dark-themed, with charts, domain tables, industry verticals, role/title signals, and an audience intelligence section aimed at sponsors.

Via MCP (Claude Desktop)

Ask Claude:

"Generate an HTML subscriber report from ~/Downloads/subscribers.csv with the title 'My Newsletter' and save it to ~/Desktop/report.html"

The tool accepts these parameters:

| Parameter | Default | Description | |---|---|---| | csv_path | (required) | Absolute path to the subscriber CSV | | format | json | json, text, or html | | title | Subscriber Analysis | Report heading shown in the HTML | | output_path | (inline) | Write the HTML to this file path | | top_n | 50 | Number of top domains to include |

As a PDF (for emailing to sponsors)

The HTML report is designed to print cleanly. To produce a PDF:

Open the saved .html file in Chrome or Safari
Press Cmd+P (macOS) or Ctrl+P (Windows/Linux)
Set Destination to "Save as PDF"
Under More settings, enable Background graphics
Save

This produces a much cleaner result than automated Puppeteer-based PDF rendering because the browser handles page breaks and dark-theme backgrounds natively.

CSV format support

Buttondown (auto-detected)

The tool recognizes Buttondown's export format by checking for its characteristic column set (id, secondary_id, email, subscriber_type, creation_date). No configuration needed.

Generic

Any CSV with an email column works. If there's no column literally named email, the tool scans column headers and picks the first one whose sample value contains @.

Customizing detection

All classification data lives in src/detectors.ts. Edit it to tune the report to your audience, then rebuild with npm run build.

// Personal mail providers (excluded from "corporate" count)
export const CONSUMER_DOMAINS = new Set([
  "gmail.com", "hotmail.com", /* ... */
]);

// Newsletter aggregators / RSS bridges
export const RSS_READER_DOMAINS = new Set([
  "kill-the-newsletter.com", "newsletters.feedbin.com", /* ... */
]);

// Org keywords that flag a domain as a notable corporate subscriber
export const NOTABLE_ORG_KEYWORDS = [
  "redhat", "microsoft", "amazon", /* ... */
];

// Role/title keywords scanned in email local parts
export const TITLE_KEYWORDS = [
  "cto", "ceo", "sre", "devops", /* ... */
];

// Domains consolidated under a parent (e.g. us.ibm.com → ibm.com)
export const DOMAIN_CONSOLIDATION: Record<string, string> = {
  "us.ibm.com": "ibm.com",
  /* ... */
};

// Domains that look corporate (2+ subscribers) but are actually personal services
export const NON_CORPORATE_DOMAINS = new Set([
  "iki.fi", "linux.com", "pobox.com", /* ... */
]);

// Industry vertical definitions used in the HTML report
export const INDUSTRY_VERTICALS: Record<string, string[]> = {
  "Cloud & Infrastructure": ["redhat", "microsoft", "amazon", /* ... */],
  "DevOps & Observability": ["datadoghq", "pagerduty", /* ... */],
  /* ... */
};

Project structure

subscriber-analyzer/
├── src/
│   ├── index.ts        # MCP server entry point + tool handlers
│   ├── analyzer.ts     # Core analysis logic + plain-text formatter
│   ├── html-report.ts  # Styled HTML report generator
│   ├── detectors.ts    # Domain/email classification data and helpers
│   └── types.ts        # TypeScript interfaces
├── package.json
├── tsconfig.json
└── LICENSE

Contributing

Pull requests welcome. A few ideas for good first contributions:

Add more RSS reader / newsletter aggregator domains to detectors.ts
Support ConvertKit and Mailchimp export formats
Expand INDUSTRY_VERTICALS and DOMAIN_CONSOLIDATION for your audience
Write tests (jest or vitest)

License

MIT — see LICENSE.

Built to analyze the DevOps'ish subscriber list.

MCP Servers