Skip to main content
Glama
newsletterss-mcp

newsletterss-mcp

by blakenetz
README.md
# newsletterss-mcp

MCP server for your Newsletterss inbox. Polls your private Atom feed
(`https://newsletterss.com/rss/<username>`, latest 10 items) every 15 min and
archives everything into SQLite with full-text search, so history builds up over time.

**Tools:** `list_newsletters`, `get_newsletter` (markdown), `search_newsletters`,
`list_senders`, `refresh_feed`.

## Configuration

| Variable                | Required               | Default                                               | Purpose                                                                                |
| ----------------------- | ---------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `NEWSLETTERSS_USERNAME` | yes                    | —                                                     | Your Newsletterss username; the server reads `https://newsletterss.com/rss/<username>` |
| `AUTH_TOKEN`            | HTTP mode (≥ 32 chars) | —                                                     | Shared secret clients must send to `/mcp` (see [Auth token](#auth-token))              |
| `DB_PATH`               | no                     | `./newsletters.db` (`/data/newsletters.db` in Docker) | SQLite archive location                                                                |
| `POLL_MINUTES`          | no                     | `15`                                                  | Feed polling interval                                                                  |
| `PORT`                  | no                     | `3000`                                                | HTTP port                                                                              |

> The feed needs no login, so anyone who knows your username can read your inbox.
> Treat `NEWSLETTERSS_USERNAME` like a password: keep it in `.env` or host secrets, never in commits.

For local runs, copy the template and fill it in; `.env` is gitignored and `npm start` loads it automatically:

```bash
cp .env.example .env
```

### Auth token

`AUTH_TOKEN` protects the HTTP endpoint (`/mcp`). Every request must carry it, either as
`Authorization: Bearer <AUTH_TOKEN>` or as `?token=<AUTH_TOKEN>`; anything else gets `401` before the request body
is read. In HTTP mode the server refuses to start if `AUTH_TOKEN` is missing or shorter than 32 characters.
`/healthz` is never protected, and stdio mode (Claude Desktop) ignores the token.

1. Generate a long random value (any URL-safe string works; hex avoids escaping in the connector URL):

   ```bash
   openssl rand -hex 32
   ```

2. Put it in `.env` for local runs, or in your host's secret store for deployments
   (`fly secrets set AUTH_TOKEN=...`). Never commit it.
3. Give it to clients:
   - The claude.ai custom connector form takes a URL, so pass the token in the query string:
     `https://<your-app>.fly.dev/mcp?token=<AUTH_TOKEN>`. That URL is now a secret too.
   - Clients that support headers (MCP Inspector, curl, other MCP hosts) should prefer
     `Authorization: Bearer <AUTH_TOKEN>`, which keeps the token out of URLs and logs.
4. To rotate, generate a new value, update the secret (`fly secrets set AUTH_TOKEN=...` restarts the app),
   then update the connector URL in claude.ai. The old token stops working immediately.

## Run locally

```bash
nvm install && npm i && npm run build   # Node version from .nvmrc
cp .env.example .env                    # then set NEWSLETTERSS_USERNAME and AUTH_TOKEN
npm start                               # http://localhost:3000/mcp
```

Development, CI and the Docker image use the Node version in `.nvmrc` (26.13.0 LTS). `package.json` `engines`
allows `^22.16.0 || >=24.0.0`: earlier releases (including all of Node 23) ship `node:sqlite` without FTS5.

## Development

```bash
npm run lint        # Biome lint + format check (warnings fail)
npm run lint:fix    # apply Biome fixes and formatting
npm run typecheck
```

`main` is protected: changes land through pull requests, and the `quality` CI job
(Biome, typecheck, build) must pass before merge.

To verify against your real feed (tools, auth, persistence, parsing quality), follow
[docs/e2e-testing.md](docs/e2e-testing.md).

## Claude Desktop (local, stdio)

```json
{
  "mcpServers": {
    "newsletterss": {
      "command": "node",
      "args": ["--no-warnings", "/abs/path/newsletterss-mcp/dist/server.js", "--stdio"],
      "env": {
        "NEWSLETTERSS_USERNAME": "your-username",
        "DB_PATH": "/abs/path/newsletters.db"
      }
    }
  }
}
```

No `AUTH_TOKEN` is needed: stdio has no network endpoint. Only archives while Desktop is running — deploy it if
you want continuous history.

## Deploy (Fly.io, needs a volume for the DB)

`fly.toml` is committed (app `newsletterss-mcp`, region `iad`). First-time setup:

```bash
fly apps create newsletterss-mcp
fly volumes create data --region iad --size 1 -a newsletterss-mcp   # single volume is intentional
AUTH_TOKEN=$(openssl rand -hex 32) && echo "$AUTH_TOKEN"   # save this; Fly won't show it again
fly secrets set NEWSLETTERSS_USERNAME=your-username AUTH_TOKEN="$AUTH_TOKEN"
fly deploy --ha=false
```

Always deploy with `--ha=false`: each Machine needs its own volume, so a second Machine would keep a separate
archive and poll the feed twice. One Machine stays always on (`min_machines_running = 1`,
`auto_stop_machines = "off"`) so polling continues.

### Continuous deployment

Every push to `main` runs the `quality` job, then the `deploy` job (`flyctl deploy --remote-only --ha=false`).
PRs never deploy, and deploys run one at a time without being cancelled. The job authenticates with an
app-scoped deploy token stored as the `FLY_API_TOKEN` repository secret:

```bash
fly tokens create deploy -a newsletterss-mcp | gh secret set FLY_API_TOKEN
```

To revoke it, list tokens with `fly tokens list -a newsletterss-mcp` and run `fly tokens revoke <id>`, then
create a new one the same way.

## Add to Claude

claude.ai → Settings → Connectors → Add custom connector →
`https://<your-app>.fly.dev/mcp?token=<AUTH_TOKEN>`