- TypeScript 83.7%
- Nix 15.9%
- Shell 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .claude/skills/alby-builder-skill | ||
| .github | ||
| docs | ||
| nix | ||
| pkgs | ||
| src | ||
| .gitignore | ||
| .mcp.json | ||
| .pre-commit-config.yaml | ||
| AGENTS.md | ||
| config.example.yaml | ||
| flake.lock | ||
| flake.nix | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
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. Passinclude_html: truewhen 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, longtext,original_text, orcontentfields 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
#Ptag 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_addrinkind:pubkey:d-tagformat).
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.