No description
  • TypeScript 83.7%
  • Nix 15.9%
  • Shell 0.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-17 20:41:17 -05:00
.claude/skills/alby-builder-skill Add public MCP user documentation 2026-06-24 18:12:45 -04:00
.github Run CI unit tests with coverage reporting 2026-10-13 22:24:31 -04:00
docs refactor: rename everything to social-reader-mcp 2026-06-28 08:17:59 -04:00
nix Fix generated config.yaml to emit literal \${VAR} placeholders 2026-07-15 23:04:43 -04:00
pkgs chore: refresh npm dependency hash 2026-10-22 11:17:36 +00:00
src Capture Mastodon/Bluesky reply refs during simplification 2026-10-14 18:02:21 -04:00
.gitignore Add public MCP user documentation 2026-06-24 18:12:45 -04:00
.mcp.json refactor: rename everything to social-reader-mcp 2026-06-28 08:17:59 -04:00
.pre-commit-config.yaml Add Nix packaging, pre-commit hooks, and CI workflows 2026-06-20 20:43:28 -04:00
AGENTS.md refactor: rename everything to social-reader-mcp 2026-06-28 08:17:59 -04:00
config.example.yaml feat: add HTTP transport with bearer-token auth for LAN access 2026-06-28 00:50:48 -04:00
flake.lock chore: update Nix dependencies 2026-11-16 10:01:25 -05:00
flake.nix refactor: rename everything to social-reader-mcp 2026-06-28 08:17:59 -04:00
package-lock.json Update npm non-breaking updates 2026-10-22 11:17:03 +00:00
package.json Run CI unit tests with coverage reporting 2026-10-13 22:24:31 -04:00
README.md Add cross-platform thread/context tools (Mastodon, Bluesky) 2026-10-13 22:33:48 -04:00
tsconfig.json feat: add HTTP transport with bearer-token auth for LAN access 2026-06-28 00:50:48 -04:00

social-reader-mcp

A read-only MCP server for Mastodon, Bluesky, and Nostr, supporting multiple accounts per platform. Built so that an agent (Hermes, Claude, or anything else speaking MCP) has tools to fetch and summarize feeds and never a tool to post, like, follow, or otherwise write anywhere.

For end-user setup, operation, cursor-safe usage, and troubleshooting, open the HTML guide at:

docs/index.html

Why this is actually read-only, not just policy-read-only

Platform Guarantee Why
Nostr Structural Only the npub (public key) is ever stored. Posting requires signing with the nsec (secret key), which never exists anywhere in this project. There is no key to misuse.
Mastodon Credential-enforced Register the OAuth app with the read scope only. The instance itself rejects any write call from that token, regardless of what code runs against it.
Bluesky Code-enforced, with a credential-free mode Bluesky app passwords are not scope-limited. If you omit app_password in the config, this account is read entirely through Bluesky's public public.api.bsky.app AppView with zero credentials. Supply an app password only if you want the real algorithmic "Following" feed; treat it as a dedicated, revocable credential.

On top of all three: this codebase contains no post_status, create_post, like, follow, repost, or publish_event function. You can grep for it.

Layout

social-reader-mcp/   (repo root: HermesSocialSummerizer/)
  src/
    server.ts           # MCP server — tool definitions and handlers
    config.ts           # Config loader with ${ENV_VAR} expansion
    state.ts            # Cursor/pagination state (atomic JSON writes)
    http-transport.ts   # HTTP transport with bearer-token auth
    unit-tests.ts       # CI-safe unit tests
    clients/
      mastodon.ts       # Native fetch, read-only Mastodon client
      bluesky.ts        # @atproto/api, handles JWT refresh automatically
      nostr.ts          # nostr-tools SimplePool, EOSE-based relay queries
  pkgs/
    social-reader-mcp.nix  # Nix package derivation
    container.nix           # Docker/OCI image
  nix/
    module.nix          # NixOS module
  config.example.yaml   # Copy to config.yaml and fill in
  package.json
  tsconfig.json
  flake.nix             # Nix flake
  .mcp.json             # Wires this server into Claude Code / Hermes

Setup

cd social-reader-mcp   # or wherever you cloned HermesSocialSummerizer
npm install
cp config.example.yaml config.yaml
# edit config.yaml — add your accounts and env var names for secrets

Create a .env file with your actual credentials:

MASTODON_MAIN_TOKEN=your_read_only_access_token
BSKY_PERSONAL_APP_PW=your_app_password   # optional

The server loads .env automatically at startup via dotenv.

Running

Verify every client method works against your live credentials:

npm test

The server speaks MCP over stdio. Run it directly to sanity-check:

node_modules/.bin/tsx src/server.ts

In practice it is launched by the MCP host (Claude Code, Hermes, etc.) via .mcp.json, which already points to the local tsx binary — no global install needed.

Running with Nix

This repo includes a flake with a Node 24 dev shell, production package, container image, and NixOS module.

nix develop
npm install
npm run typecheck
npm test
npm run build

Build the production package:

nix build

The result contains a stdio MCP binary:

./result/bin/social-reader-mcp

Set SOCIAL_READER_MCP_CONFIG, CURSOR_STATE_PATH, and the credential env vars required by your config before launching it from an MCP host.

The flake also exports nixosModules.default. The module writes a generated non-secret config with ${ENV_VAR} placeholders, creates a writable cursor state directory, and installs a social-reader-mcp wrapper on PATH. Secret token values still come from the environment of the MCP host that launches the wrapper.

Running over HTTP (LAN)

To make this server reachable from other machines on your LAN — other Hermes instances, Claude Code on a different box — set SOCIAL_READER_MCP_TRANSPORT=http. The stdio path is completely unchanged when this variable is unset.

Environment variables

Variable Default Description
SOCIAL_READER_MCP_TRANSPORT stdio Set to http to enable the HTTP listener.
SOCIAL_READER_MCP_HTTP_HOST 127.0.0.1 Address to bind. Change to a LAN IP to expose on the network.
SOCIAL_READER_MCP_HTTP_PORT 8787 Port to listen on.
SOCIAL_READER_MCP_HTTP_TOKEN (required) Literal bearer token.
SOCIAL_READER_MCP_HTTP_TOKEN_FILE (alternative) Path to a file whose content is the token (trailing whitespace stripped). Preferred for systemd deployments — keeps the raw secret out of systemctl show output.

The server will refuse to start if no token is configured. It will also refuse to bind on a non-loopback address without a token.

Quick start

export SOCIAL_READER_MCP_TRANSPORT=http
export SOCIAL_READER_MCP_HTTP_HOST=0.0.0.0   # listen on all interfaces
export SOCIAL_READER_MCP_HTTP_PORT=8787
export SOCIAL_READER_MCP_HTTP_TOKEN=mysecrettoken
export MASTODON_MAIN_TOKEN=...               # your normal credentials
node_modules/.bin/tsx src/server.ts

Verify the server is up

curl http://localhost:8787/healthz
# → {"status":"ok"}

Call a tool (tools/list)

curl -s http://192.168.1.10:8787/mcp \
  -H "Authorization: Bearer mysecrettoken" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq .

Wire into a remote MCP host

{
  "mcpServers": {
    "social-reader-mcp": {
      "type": "http",
      "url": "http://192.168.1.10:8787/mcp",
      "headers": {
        "Authorization": "Bearer mysecrettoken"
      }
    }
  }
}

Two processes, one server — if you want to use both stdio (for local Claude Code) and HTTP (for LAN) simultaneously, run two separate processes with different CURSOR_STATE_PATH values. Running two live consumers against the same cursor file would race over the same per-account cursor.

NixOS deployment — the flake exports nixosModules.default with services.social-reader-mcp.http options. See the NixOS module section and nix/module.nix for the full option set.

Running as a container

Build the Docker/OCI-compatible image:

nix build .#container
docker load < result

The image is named social-reader-mcp:latest. It is still a stdio MCP server, not an HTTP service, so run it interactively from your MCP host:

{
  "mcpServers": {
    "social-reader-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/.env",
        "-e", "SOCIAL_READER_MCP_CONFIG=/config/config.yaml",
        "-e", "CURSOR_STATE_PATH=/data/cursor_state.json",
        "-v", "/path/to/config.yaml:/config/config.yaml:ro",
        "-v", "/path/to/social-reader-mcp-data:/data",
        "social-reader-mcp:latest"
      ]
    }
  }
}

Do not publish ports for the container; the MCP host talks to stdin/stdout.

Tools

Call list_accounts first to get the account IDs used by all other tools.

Timelines / feeds

Tool Platform Description
list_accounts all Returns configured account IDs grouped by platform
mastodon_home_timeline Mastodon Home timeline; stateless, pass since_id yourself
bluesky_timeline Bluesky Following feed; stateless, pass since yourself
nostr_following_feed Nostr Notes from followed pubkeys; stateless, pass since_ts yourself

Engagement history (strong interest signals)

Tool Platform Signal
mastodon_favourites Mastodon Posts you favourited
mastodon_reblogs Mastodon Posts you boosted
mastodon_bookmarks Mastodon Posts you saved/bookmarked
bluesky_likes Bluesky Posts you liked
bluesky_reposts Bluesky Posts you reposted
nostr_my_reactions Nostr Kind 7 reactions you published
nostr_my_reposts Nostr Kind 6 reposts you published
nostr_my_bookmarks Nostr NIP-51 kind 10003 bookmark list
nostr_my_zaps Nostr Kind 9735 zap receipts where you are the sender

Utility

Tool Description
reload_config Reloads config.yaml and reinitializes all clients without restarting the server. Also hot-reloads any client code changes.

Point lookups and thread context

Dereference a specific item by ID/URI - not a feed, no cursor or pagination concept applies. Use these to pull up a reply's parent or a thread's other replies when an already-collected candidate doesn't stand alone, e.g. a Nostr self-reply carrying the source link for the note above it.

Tool Platform Description
mastodon_status_context Mastodon Full ancestor chain and reply tree for a status, via the instance's own /statuses/:id/context endpoint.
bluesky_post_thread Bluesky Ancestor chain and reply tree for a post, via getPostThread (depth/parent_height bound how far the AT Protocol server itself walks the tree).
nostr_get_event Nostr Fetch one Nostr event by hex event ID.
nostr_get_events Nostr Fetch up to 50 Nostr events by hex event ID in one relay query.
nostr_get_profile Nostr Fetch a Nostr kind-0 profile by hex pubkey.
nostr_get_article Nostr Fetch a NIP-23 long-form article by 30023:<pubkey>:<d-tag> address.

Parameters

Every tool except list_accounts and reload_config requires account_id (a string matching one of the IDs in config.yaml). Timeline tools accept an optional limit (default 40 for Mastodon/Bluesky, 100 for Nostr). nostr_following_feed also accepts hours (default 24, capped at one week regardless of what's requested).

Response-size controls are available for agent-friendly summaries:

  • Mastodon tools omit raw HTML fields (text_html, original_text_html) by default. Pass include_html: true when an agent explicitly needs the source HTML rather than the plain-text fields.
  • Mastodon, Bluesky, and content-returning Nostr tools accept max_content_length. When set, long text, original_text, or content fields are truncated with a suffix such as …[+123 chars] so the caller can tell how much text was omitted.

No server-side cursor

The three timeline tools (mastodon_home_timeline, bluesky_timeline, nostr_following_feed) are stateless - this server tracks no "last seen" position for any caller. Pass since_id (Mastodon), since (Bluesky), or since_ts (Nostr) yourself if you want only what's new since your own previous fetch; omit it for the most recent window. This server's own role is limited to protecting the upstream API credentials it holds - every timeline tool enforces a hard ceiling on lookback depth (one week) and volume (limit/max_pages) regardless of what a caller asks for, but remembering where a particular consumer left off is entirely that consumer's own responsibility.

Note: the AT Protocol has no native server-side time filter for Bluesky's feed, so since there is applied by paginating and stopping early / filtering client-side, not by a narrower upstream query - the other two platforms get a genuine server-side bound.

Engagement signal notes

  • Nostr zaps are fetched from relay kind 9735 events using the #P tag filter (sender pubkey). This gives full event context — which post was zapped, recipient pubkey, amount, and message — without requiring a Lightning wallet connection.
  • Bluesky saved posts are off-protocol and private with no API exposure. Not currently fetchable.
  • Nostr bookmarks may contain both notes (event_id) and long-form articles (article_addr in kind:pubkey:d-tag format).

Wiring into Claude Code

.mcp.json is already configured:

{
  "mcpServers": {
    "social-reader-mcp": {
      "command": "/path/to/HermesSocialSummerizer/node_modules/.bin/tsx",
      "args": ["/path/to/HermesSocialSummerizer/src/server.ts"]
    }
  }
}

Update the paths to match your checkout location.

Wiring into Hermes

mcp_servers:
  social-reader-mcp:
    command: /path/to/HermesSocialSummerizer/node_modules/.bin/tsx
    args: ["/path/to/HermesSocialSummerizer/src/server.ts"]
    env:
      MASTODON_MAIN_TOKEN: "..."
      BSKY_PERSONAL_APP_PW: "..."

Example cron prompt:

/cron add "0 8 * * *" "Call list_accounts. For every configured Mastodon,
Bluesky, and Nostr account, fetch its recent timeline and all engagement
history tools. Summarize new posts by theme, weighting heavily any content
whose author or topic overlaps with the account's engagement history
(bookmarks, likes, zaps, reposts). Deliver digest to Matrix."

Credential setup per platform

Mastodon — register an OAuth app on your instance (Settings > Development) with the read scope only. Use the resulting access token. The instance will reject any write attempt from this token at the server level.

Bluesky — generate a dedicated app password (Settings > App Passwords). Keep it separate from any password shared with another tool; it is independently revocable. Omit it entirely for public-only reads.

Nostr — only your npub (public key) goes in config.yaml. The nsec never touches this project. No key management, no risk of key exposure.