by matthewdonsemail-lab
Run and manage social media accounts from the command line or through AI agents, handling DMs, posts, replies, and outbound messages across X, Discord, Slack, Instagram, Reddit, LinkedIn, and Facebook in your own voice.
Log provides a unified CLI and MCP server that lets an AI agent or a developer interact with multiple social‑media platforms. It can read inboxes, watch live messages, draft replies, and send actions such as likes, follows, reactions, or voice notes, all while keeping the data on the local machine.
npx -y @listeningkit/log
(The installer also adds the log and logMcp commands.)claude mcp add log -- logMcp or the appropriate harness plugin.log twitter dms --account <handle> --waiting, log discord read --account <name> --channel "#general", or log voice --to <handle> --text "Draft".--live to actually send messages; without it the command runs as a dry‑run.~/.logCli/log.db; reads are sub‑millisecond.logMcp) that can be hot‑reloaded without restarting the agent.Q: Do I need API keys for the platforms? A: No. Log uses browser‑based authentication (cookies or interactive login) and its own API clients.
Q: Will my data be sent to a third‑party server?
A: All events, messages, and media transcriptions are stored locally in log.db. Only optional hosted services (e.g., voice cloning, Jina reranking) require API keys you provide.
Q: Can I run Log on Windows? A: Yes. The installer script supports PowerShell, and the CLI works on macOS, Linux, and Windows.
Q: How does the live push work? A: Each account runs a single watcher that holds the platform’s push socket (Discord gateway, Slack socket, etc.). New events are appended to the database and immediately forwarded to the connected MCP server.
Q: What happens if the server code is updated while a job is running?
A: logMcp acts as a reload proxy; it waits for in‑flight calls to finish, starts the new server version, and swaps it without interrupting long‑running jobs.
curl -fsSL https://log.listeningkit.com/install.sh | sh
claude mcp add log -- logMcp
"Read my X DMs and tell me who's waiting on me."
The old inbox and the encrypted X Chat, read as one.
log twitter dms --account <name> --waiting
Every new message is pushed to your agent the moment it lands.
log discord read --account <name> --channel "<chat>"
log slack read --account <name> --channel "<chat>"
log instagram dms --account <name>
Every draft is checked against how you really write to that person before it goes.
log voice --to <handle> --text "<draft>"
Listings kept live across local accounts, and groups read for people asking for a service.
log facebook listings
log facebook join group --account <name> --group <url>
log runs your social accounts from the command line, or from your AI agent. It reads DMs, group chats, replies and notifications, and it sends messages, replies, likes, follows, reactions and voice notes for you. It's one command, log, and one MCP server, logMcp, and it runs on your own machine with your own accounts. Nothing acts until you say so: every command that changes something is a dry run until you add --live. It's free and open source.
curl -fsSL https://log.listeningkit.com/install.sh | sh # macOS and Linux
irm https://log.listeningkit.com/install.ps1 | iex # Windows (PowerShell)
curl -fsSL https://log.listeningkit.com/install.sh | sh -s -- --skills all # also every play as a skill
This installs the log and logMcp commands, and Python with everything the platform engines need. It writes your settings to ~/.logCli/.env. Already have Bun? bun add -g @listeningkit/log installs just the commands. Already have log? --skills all --skillsOnly adds only the skills; on Windows, set $env:LOG_SKILLS = "all" before the PowerShell line. More: docs/install.md.
Add the account once, sign it in, then check that the platform still accepts it:
| Platform | How to sign in |
|---|---|
| X | log twitter cookies save --account <handle>: paste auth_token, ct0 and twid from a cookie-export extension |
log linkedin cookies save --account <publicId>: paste li_at and JSESSIONID |
|
| Slack | log slack cookies save --account <name>: paste the d cookie |
| Discord, Reddit, Instagram | log localAccount add --platform <platform> --account <name>, then log inspect start --account <name>, sign in by hand in the window that opens, and log inspect do stop --account <name> to save the session |
log localAccount add --platform facebook --account <name>, then log facebook connect --account <name> |
Then check it with log <platform> session check --account <name>, which sends nothing. The answer is loggedIn, loggedOut or restricted. Cookies are always typed into a masked prompt and never passed as flags. More: docs/accounts.md.
| Agent | How to connect |
|---|---|
| Claude Code | claude mcp add log -- logMcp |
| Hermes | hermes plugins pack install https://log.listeningkit.com/hermes-pack.yaml: the log plugin for Hermes, tools, skills, dashboard tab and router hook in one install |
| Codex, Cursor, OpenCode and other MCP clients | add logMcp as a stdio MCP server: docs/mcp.md |
| Claude, ChatGPT and Grok, or an agent on a server | the hosted server, https://mcp.listeningkit.com/mcp, over OAuth |
Then ask in plain words: "read my X DMs and tell me who's waiting on me". log's router names the play for that request, and the agent follows its steps. Every harness, and what each one can do: Works in every harness.
| Platform | What log does | How it talks to the platform |
|---|---|---|
| X | DMs and X Chat, notifications, followers, replies, posts, likes, follows, lists, reactions, voice notes, queues | its own API client, one session per account, no browser |
| Discord | DMs, groups and server channels, live; sends, reactions, voice notes, files | its own API client and the live gateway, no browser |
| Slack | DMs and group DMs in every workspace, live; sends, reactions, voice notes | its own API client and the live socket, no browser |
| DM threads, live; sends, photos, reactions, voice notes | its own API client and the realtime connection, no browser | |
| Marketplace listings, groups, warm-up | the account's own browser, opened once a day through a proxy in its home country | |
| session check (new) | its own API client | |
| session check (new) | its own API client |
--skills all, your agent picks the right one from what you say.~/.logCli. Many accounts? Keep them in Twenty, an open-source CRM, so every machine, agent and teammate sees the same ones.A harness is the agent app you talk to log through. log is the same MCP server in all of them, with the same tools under the same names. What changes is how log's guidance reaches the model and how new messages reach it:
| Harness | Connects | How it's told what to do | How new messages reach it | Views and sign-in |
|---|---|---|---|---|
| Claude Code | local or hosted | its prompt hook runs the router on every prompt | hooks on every prompt and after every tool call | text; sign-in in the window on your screen |
| Codex | local or hosted | its prompt hook | hooks on every prompt and around tool calls | text |
| Hermes | local or hosted | the log plugin's pre_llm_call, before every model call |
the same hook, before every model call | text, plus a log tab in the Hermes dashboard |
| OpenCode | local | its prompt hook | its plugin's hooks | text |
| Antigravity | local | its prompt hook | its hooks | text |
| Cursor | local or hosted | getGuide({ ask }) (Cursor's prompt hook can't add context) |
sessionStart and postToolUse hooks |
MCP Apps: report and browserView inline |
| Claude (web, desktop, mobile) | hosted | getGuide({ ask }) |
when it asks | MCP Apps inline |
| ChatGPT | hosted | getGuide({ ask }) |
when it asks | MCP Apps inline |
| Grok (xAI API) | hosted | getGuide({ ask }) |
when it asks | text |
The full table, written from the code (HARNESSES in src/agentHooks/harness/types.ts), with each hook's text limit and where its hooks live: docs/harnesses.
Hermes runs all day, on your machine or a server, and talks to you on Telegram, Slack and its desktop app. The log plugin gives it log's tools, every play as a skill, and a log tab in its dashboard. Hermes reads freely, and every send, reply or post asks you first.
hermes plugins pack install https://log.listeningkit.com/hermes-pack.yaml
One command installs and enables both halves: log (log's tools, every play as a skill, the dashboard's log tab) and logHooks (the router hook). Hermes shows what the pack installs, pinned to an exact commit, and asks once. Install log itself first; the hook finds it on its own.
Each thing log can do has one name and works the same way from the CLI, the MCP server and the log console, on every platform. The platform is something you pass in, never a default:
log chats list, log messages read|send|react|watch and their MCP tools (chatsList, messagesRead, messagesSendLive) work on X, Discord, Slack, Instagram and Facebook, the platform taken from the account.log sessions signIn (MCP: sessionsSignIn) opens the account's own browser, you sign in on the platform's login screen, and the session is saved only once the platform shows you signed in. A signed-out browser never overwrites a good session. log sessions check answers for every account at once.log console is the same operations as a terminal console, or as a web console on your own machine with --web. Every console screen has a matching command.report draws a view from log's own data, and browserView shows an account's live browser in the chat, where the host draws MCP Apps. Elsewhere both come back as text.log keeps everything it needs to answer you on your own machine, in one local database, ~/.logCli/log.db. The platforms push what happens to it as it happens. So when you or your agent asks "what did they say?", log reads its own database in about a millisecond instead of asking the platform again, which takes seconds.
In plain words:
log.db once, as an event.Claude Code starts logMcp once. logMcp is a small proxy that never exits, and it runs the real server as a child process. When log's code changes, it waits until no call is in flight, starts the new code, and swaps it in. A long job, like a queue sending over an hour, is never cut off: it keeps running in the old server until it ends, and every new call goes to the new code. If the new code doesn't start within 30 s, the old code keeps serving. Your agent keeps working without a restart. This design was picked from four open-source options by a SubQ matrix (docs/decisions/mcpReload).
Each play is a workflow written step by step, with the words people use to ask for it. The router matches what you typed against every play, so the agent starts from the right steps instead of guessing:
log plugin's pre_llm_call.getGuide({ ask: "<your words>" }) first. It's the same router, so the same prompt gets the same play. A golden set of prompts checks that (src/useCases/router/fixtures/golden.json).getGuide({ useCase }). A play that is close but below the bar, or a near tie, shows a short menu and loads nothing. Building or fixing log itself is never a play.Your agent doesn't have to ask what's new. Every account's watcher holds the platform's own push channel, and the hooks put what arrived in front of the agent before its next step. In Hermes, OpenCode and Claude Code (through a Monitor), a push loop also starts a turn when a message lands while the agent is idle (docs/liveInbox.md). The hooks are answered by the warm context service on your machine (port 47317), or by a one-off process when it's down:
What your agent sees, added to its turn (the handles here are made up):
log-cli accounts: each one's session (the platform's own answer) and what its governor allowed today:
twitter yourHandle: session loggedIn, 19/500 requests, 0/240 writes today, its one session open
slack yourWorkspace: session loggedIn, 3/500 requests, 0/40 writes today
>>> PLAY MATCH: the prompt matches the log play twitter/dmInbox (Reading the DM inbox: who is waiting on you).
Its steps load with getGuide({ useCase: "twitter/dmInbox" }).
>>> X LIVE: each X account's unread counts right now, from X's own ViewerBadgeCounts:
@yourHandle: 12 notifications, 0 DMs and 0 X Chat unread
!!! GAPOPENED slack yourWorkspace: behind since its watcher restarted; it catches up through its own session, and a send that needs its context waits for that
log.db.The voice gate checks what goes out. The judge checks what comes in, before your agent reads a word of it. It runs where every new message is picked up for a session, so the hooks and the push loop both get judged text:
LOG_JUDGE_MODEL_OFF=1 turns it off.Every model can read text, even one that can't see images. So every piece of media is turned into text when it arrives and kept in log.db with one small preview picture. No media file stays on disk.
A video with someone talking reads like this:
[video 0:32, 4 scenes, speech: [0:00-0:08] screen: a whiteboard that says "Q4 plan" | speech: "so this is the plan" · ...]
A video with no sound, like motion graphics, says no sound and is told by what changes on screen. This design takes the best part of three open-source systems that a SubQ matrix ranked out of 17 found on GitHub:
Three models run on your own machine, with no key. Four are hosted, and each needs its key:
| Model | Runs | What it does |
|---|---|---|
| all-MiniLM-L6-v2 (23 MB) | your machine | meaning search over every conversation, your voice index, matching what you typed to a play |
| LFM2.5-VL-450M (352 MB) | your machine | describes every picture and video frame as text |
| wolf-defender prompt injection small | your machine | the judge's model: flags prompt injection in what comes in |
SubQ subq-snap-1.1 |
hosted, SUBQ_API_KEY |
the voice gate: does a draft sound like you |
| Jina embeddings v5 and reranker v3.5 | hosted, JINA_API_KEY |
the AI tells check, ranking a chat's history for the gate, and a meaning vector for each piece of media |
| AssemblyAI | hosted, ASSEMBLYAI_API_KEY |
what was said in a voice note or a video |
| Inworld or Fish Audio | hosted, INWORLD_API_KEY or FISH_API_KEY |
a voice note in your cloned voice, only when you ask |
What your machine needs, measured here on 2026-11-09 (16 threads, CPU only):
Building the indexes on a new machine, in this order:
log search index reads every conversation once and builds the keyword and meaning indexes.log voice index builds your voice from what step 1 saved.log voice aiIndex builds the AI tells check.After that, new messages are added as they arrive, and pictures are described as they land.
Each model, its numbers and how each index works: docs/models.md.
The storage follows the ideas in Martin Kleppmann's Designing Data-Intensive Applications (DDIA):
| DDIA idea | What it means | Where it is in log |
|---|---|---|
| The system of record | One place holds the truth, written once | the events table: every message, reaction and notification, appended once by its id |
| Derived data | Everything else is worked out from the record, and can be rebuilt | chats, messages, people and who did what, checked and rebuilt from the events by log storage verify and log storage rebuild; media text and transcripts are kept beside them |
| Idempotence | Doing something twice has the same effect as once | an event is stored by its id, a transcript by its audio's hash, a media row by its message and name |
| Fencing | An old process that wakes up late can't overwrite the new one's work | each account's watcher holds a generation number, and a replaced one's writes are refused |
| Big files outside the database | Keep the bytes in a file store and only a small pointer in the database | log goes one step further: it keeps only the text and a small preview, and drops the file |
Measured on this project's own log.db on 2026-11-08, not estimated:
| What | p50 | p95 | p99 | p99.9 | Measured with |
|---|---|---|---|---|---|
Read a Discord chat from log.db (1,000 reads) |
0.6 ms | 1.1 ms | 1.6 ms | 3.1 ms | bun scripts/inbox/benchDbRead.ts |
| Claim a chat so no other agent answers it | 1 ms | 5 ms | 16 ms | 27 ms | log timing (79 claims) |
| Lock the account for one call | 0.2 ms | 0.3 ms | 0.4 ms | 0.5 ms | log timing (62 calls) |
| Match what you typed to a play (in the warm service) | 12 ms | 36 ms | 47 ms | n/a | bun scripts/useCases/benchRouter.ts |
| Read the same Discord chat from Discord itself | 2.3 s | 3.6 s | 5.1 s | 6.0 s | log timing (190 reads) |
That last row is why log reads its own database: asking the platform takes thousands of times longer. Sends are slower again, on purpose. Each account keeps human pacing between actions, and a refusal from a platform stops the run.
Every call is timed: log timing shows p50, p95 and p99 for every tool and each step inside it, and log timing --call <id> shows one call step by step.
log.db keeps that from happening.What's built, what's next and what's planned is kept in one pinned issue: Roadmap #200. In short:
| Area | Built | Next |
|---|---|---|
| Security | the judge's rules and local model | judging images, a guard before tool calls, taint, a canary token, an attack-set benchmark, an encrypted account store |
| The record (soron, #197) | search by DM, group or channel | keeping edits and deletions, capturing the conversation around a personal mention (kept after a ban), judging each message the moment it arrives |
| Turn awareness (spec) | typing on Discord and Slack | X Chat |
| Tools | tool health | recording which tools the router offered, so unused tools can be told apart from unseen ones |
| Your day | a morning debrief: who is waiting, what you owe, what was held overnight | |
| Voice | cloned voice notes | voice-note replies in your voice, then calls, with your yes per call |
| Browser | human mouse: Fitts's-law timing, corrective moves, tremor (#201) | sign-ins moving from AdsPower to Camoufox, browser-fingerprinted HTTP for X and Discord |
| Every harness (spec, #196) | views in Cursor, Claude and ChatGPT where the host draws MCP Apps | a ChatGPT connector, a smaller inbox tool profile, a Claude Desktop extension, a render test on every PR |
| Speed | the prompt hook under 150 ms |
Built here means written, tested and in an open PR; each lands in a release once merged.
Newest first. Each release pins the local models it runs with (log models), and log update moves code, harness plugins and models to the release together (docs/updates.md).
| Version | Date | What's in it | Models |
|---|---|---|---|
| 0.2.1 | 2026-11-20 | The relate graph, the live inbox push (messages during tool calls, burst batching, late copies dropped), inbox labels and ignoring a server or chat (+2 more) | not pinned (newest by name) |
| 0.2.0 | 2026-11-15 | The one-command Hermes pack, the catalog review, the README rewrite and the catch-up machine (+1 more) | not pinned (newest by name) |
log --help # every command
log <platform> session check --account <a> # is the session still signed in?
log twitter dms --account <a> [--with <handle>] # the inbox, or one person in full
log twitter dm --account <a> --userId <id> --text "<message>" [--live --approvedBy <who>]
log twitter queue build|plan|run # several sends, at random times
log chats list --account <a> # any platform: the account's chats
log messages read --account <a> --chat "<chat>" # any platform: one chat's messages
log sessions check # every account, the platform's own answer
log sessions signIn --account <a> # sign in from the account's own browser
log console [--web] # the local console, in the terminal or the browser
log watchers # each account's one live watcher
log discord read|send --account <a> --channel "<chat>"
log slack read|send --account <a> --channel "<chat>"
log instagram dms|send --account <a>
log voice --to <handle> --text "<draft>" # check a draft against your voice
log search "<query>" # search every conversation
log inbox # claim a chat, see what was done in it
Every command, flag, MCP tool and hook: docs/reference.md.
The full docs are at log.listeningkit.com/docs, built from docs/:
| Tab | What's in it |
|---|---|
| Get started | install, add your accounts, connect your agent, each harness, using log well |
| Use cases | the plays, step by step |
| Platforms | X, Discord, Slack, Facebook, Reddit and LinkedIn |
| Reference | every command, MCP tool and hook, error codes, agent guides |
| How it works | how log decides what happened, the models it uses, Twenty, browsers, proxies, each platform's API and the diagrams |
Where each page sits is set in docs/site.json, and a commit check refuses a page that isn't placed.
git clone https://github.com/matthewdonsemail-lab/log
cd log
bun install # also installs the git hooks
bun link # puts this checkout's log and logMcp on your PATH
bun run check
Every commit and push runs the same checks CI does (lefthook): the docs and reference match the code, the naming and layout are right, there are no comments in code, the specs hold, and the tests pass. The rules agents work by are in AGENTS.md.
Some plays link to services log works with (treg, Memelord, Inworld, Fish Audio), and those links carry ListeningKit's referral or affiliate code (ref= or aff=). Using them costs nothing extra; drop the code from the address if you'd rather not. Every skill with such a link says so.
MIT
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by lharries
Enables searching, reading, and sending personal WhatsApp messages and media through a Model Context Protocol (MCP) server, storing all data locally in SQLite and exposing controlled tools for LLMs like Claude.
by stickerdaniel
Enables AI assistants to read and interact with LinkedIn data—including profiles, companies, jobs, and messages—through a locally‑run MCP server that operates on your own authenticated browser session.
by caol64
Automatically format Markdown articles and publish them to WeChat public accounts, supporting theme selection, image upload, and AI integration.
by korotovsky
Provides a powerful Model Context Protocol interface for Slack workspaces, enabling message retrieval, search, and optional posting via Stdio or SSE transports without requiring bot permissions.
by iFurySt
Provides authenticated access to XiaoHongShu (RedNote) notes, supporting keyword search, note retrieval by URL, and cookie persistence via a Model Context Protocol server.
by karanb192
Enables Claude Desktop and other AI assistants to browse Reddit, search posts, fetch full comment threads, and analyze user activity with clean, LLM‑optimized responses.
by chigwell
Provides a full‑featured Telegram integration for MCP‑compatible clients, enabling programmatic access to chats, messages, contacts, profile management, and group administration.
by line
Integrates the LINE Messaging API with a Model Context Protocol server, enabling AI agents to send text, flex, broadcast messages, retrieve user profiles, and manage rich menus on a LINE Official Account.
by ZubeidHendricks
Provides a standardized interface for interacting with YouTube content, enabling video retrieval, transcript access, channel and playlist management, and advanced analytics through the Model Context Protocol.
{
"mcpServers": {
"logMcp": {
"command": "npx",
"args": [
"-y",
"@listeningkit/log"
],
"env": {}
}
}
}claude mcp add logMcp npx -y @listeningkit/log