chatmux MCP server
Commit Aug 25, 2026Provides a local-first data layer for LINE and Telegram chats, exposing MCP tools for AI clients to read, search, and send messages.
Also known as echoedinvoker/chatmux
- Stars
- 1
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Aug 25, 2026
- License
- MIT
What is chatmux MCP?
chatmux provides a local-first data layer for LINE and Telegram chats, exposing MCP tools for AI clients to read, search, and send messages. It exposes 8 tools, such as list_chats, read_messages, read_events.
Summary generated from the project's README
About chatmux MCP server
chatmux acts as a local-first data layer that connects instant messaging platforms like LINE and Telegram to AI clients. It functions as a central daemon that manages message storage using a combination of JSONL files and a SQLite database with FTS5 for full-text search. By using child-process adapters, it bridges the gap between chat protocols and the Model Context Protocol, allowing developers to interact with their personal chat history through standardized tools.
Users can integrate this server with clients like Claude Code by connecting to a TCP port on 127.0.0.1. The system provides a variety of tools for managing communication, including searching messages, reading chat histories, and sending new messages through a safety rail that tracks errors and limits rates. It also supports local media handling by providing file paths for images and stickers. Because it is designed for local use, all decrypted message content remains on your machine within your specified data directory.
What you can do with it
- 1Search through chat historyAsk the AI to find specific information within your past conversations using full-text search.
- 2Automate message repliesInstruct an AI agent to send a response to a contact via the LINE or Telegram platform.
- 3Monitor real-time chat eventsCreate a custom notification system that reacts whenever a new message arrives or an old one is edited.
- 4Retrieve chat mediaRequest the local file path for an image or sticker sent in a conversation.
Written from the project's README. Every use case is checked against a quote from it.
chatmux MCP tools 8
Detected from the READMElist_chatsread_messagesread_eventssearch_messagessend_messageget_mediaprobe_latestget_status
| list_chats | — | |
| read_messages | — | |
| read_events | — | |
| search_messages | — | |
| send_message | — | |
| get_media | — | |
| probe_latest | — | |
| get_status | — |
Configuration
CHATMUX_DATA_DIR
| Name | Description | |
|---|---|---|
| CHATMUX_DATA_DIR | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableechoedinvoker/chatmux is public and reachablegithub.com/echoedinvoker/chatmux ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-25github.com/echoedinvoker/chatmux ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubchatmux
Local-first personal chat data layer daemon. Connects IM platforms (v0.1: LINE) via child-process adapters, stores messages to JSONL + SQLite/FTS5, exposes MCP tools for AI clients.
The three repos
chatmux is the core. Platforms plug in below it, consumers sit above it, and both sides of that boundary live in their own repos:
| Repo | Role |
|---|---|
| chatmux (this one) | Core daemon: storage, safety rail, MCP server, LINE adapter |
| chatmux-adapter-telegram | Second platform adapter (Telegram, MTProto user session) |
| chat.nvim | Reference consumer: read and reply to chats inside Neovim |
Adapters speak the adapter protocol; consumers speak MCP. Either side can be replaced without touching the other.
Quickstart
1. Install
git clone https://github.com/echoedinvoker/chatmux.git
cd chatmux
bun install
2. Decide whether to connect an account yet
With no adapters.json, bun run start launches the LINE adapter, which means step 3 puts
your LINE account on the line — read Account Risk Warning before you
run it. If you would rather look around first, start with no adapter at all:
mkdir -p ~/.local/share/chatmux
cat > ~/.local/share/chatmux/adapters.json <<'JSON'
{
"adapters": [],
"mcp": { "port": 7717 }
}
JSON
bun run start
The daemon comes up with storage and the full MCP interface — you can initialize, list tools,
and read resources. There is simply no chat data behind them until an adapter is connected. Set
CHATMUX_DATA_DIR to keep this trial run out of your real data directory:
CHATMUX_DATA_DIR=/tmp/chatmux-trial bun run start
Each entry in adapters takes platform, a command string, and an args array
(plus optional cwd and env):
{ "platform": "telegram", "command": "python", "args": ["-m", "chatmux_adapter_telegram"] }
For Telegram, follow the setup in chatmux-adapter-telegram — it has its own credentials and login flow, and does not involve LINE.
3. First login (QR code)
bun run start
# A QR code will appear in the terminal
# Open LINE on your phone → open the QR scanner → scan
# iOS: Home → the scan icon
# Android: Home → Add friends → QR code
# After successful login, authToken is saved for future auto-login
4. Connect Claude Code
Register the daemon's MCP endpoint with Claude Code:
claude mcp add --transport http chatmux http://127.0.0.1:7717/mcp
claude mcp list # chatmux: ... - ✔ Connected
The daemon listens on two transports at once: a TCP port on 127.0.0.1 (default 7717) for
standard MCP clients like Claude Code, and a unix socket for same-host sidecar consumers like
chat.nvim. Use the TCP url for Claude Code — the MCP
spec only defines stdio and streamable HTTP transports, so no MCP client accepts a unix socket path.
Port is configurable via CHATMUX_MCP_PORT, or mcp.port in adapters.json; set it to 0 to
disable the TCP listener. See docs/mcp-interface.md.
Architecture
LINE adapter ←── stdio JSON-RPC ──→ core daemon ←── MCP Streamable HTTP ──→ Claude Code
(Node+tsx) (child process) (Bun) (127.0.0.1 TCP / unix) (MCP client)
├─ SafetyRail
├─ Storage (JSONL → SQLite/FTS5)
├─ Adapter Runner
└─ MCP Server
- Core daemon (Bun): central process managing storage, safety, and MCP server
- LINE adapter (Node+tsx): child process connecting to LINE via IOSIPAD slot
- Storage: JSONL append-only truth source + SQLite/FTS5 queryable view
- MCP server: Streamable HTTP over TCP (standard MCP clients; loopback by default, settable for containers) + unix socket (same-host sidecars), 8 tools + 4 resources
MCP Tools
| Tool | Description |
|---|---|
list_chats |
List chats with last message preview, search, pagination |
read_messages |
Read messages from a chat, paginated by timestamp |
read_events |
Tail the event log from an opaque cursor — resumable, survives backfill reordering, and re-delivers a message when it is edited or retracted |
search_messages |
Full-text search (CJK supported via FTS5 trigram + LIKE fallback) |
send_message |
Send message through SafetyRail (rate-limited, error-tracked) |
get_media |
Local file path for a message's image or sticker; downloads and caches on first call |
probe_latest |
Diagnostic, read-only: ask the adapter for a chat's newest N messages without landing them |
get_status |
System status: adapter connection + storage stats |
MCP Resources
| URI | Description |
|---|---|
chat://chats |
All chat list |
chat://chats/{id}/messages |
Recent messages for a chat |
chat://chats/{id}/info |
Chat details with members |
chat://status |
System status |
Writing a consumer
Core exposes primitives, not policy. Anything that decides what matters — which chats are worth surfacing, where a notification goes, when to stay quiet — belongs in a consumer, on the far side of the MCP boundary.
examples/notifier/ is a working reference: it tails the event
log with a persisted cursor and hands each message to a hook you fill in. Its
mcp-client.ts uses raw fetch rather than the TypeScript SDK, so it doubles as a
wire-protocol reference for consumers in any language.
systemd Service
cp config/chatmux.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now chatmux
Edit WorkingDirectory to point at your clone before copying it.
How it comes back
The unit ships Restart=always, not on-failure. A chat backend is supposed to be there
all day, and there are three ways it can stop being there — it crashes, something sends it
a signal, or it exits cleanly — of which on-failure only recovers from the first.
systemctl --user stop still stops it: a stop you asked for is not a failure, under either
setting.
⚠️ If you are on an older unit with
Restart=on-failure,kill -TERMwill not bring it back — and that is not a missing restart policy. systemd counts SIGTERM, SIGHUP, SIGINT and SIGPIPE as an intended stop, soon-failureleaves the service sitting ininactiveafter any of them. Onlykill -9(SIGKILL) counts as a failure there.With the
Restart=alwaysthis unit now ships, TERM comes back too — measured 2026-08-02:kill -TERM $MainPIDmovedNRestarts1 → 2 and produced a newMainPIDwithin the 10sRestartSec. That makes TERM the useful test:kill -9restarts under either setting, so it cannot tell you which one is in effect. If you want to confirmalwaysis live, send TERM and watchsystemctl --user show chatmux -p MainPID,NRestartschange.
StartLimitIntervalSec=300 / StartLimitBurst=5 cap a crash loop: five starts inside five
minutes and systemd stops trying, leaving the unit failed for you to look at rather than
restarting into the same wall forever. Clear it with systemctl --user reset-failed chatmux.
Containers
A systemd user service is the intended way to run chatmux. If you want it in a
container instead, deploy/container/ is a reference that builds
and answers — not an official image, and it runs zero adapters, because adapters
hold logged-in sessions and a container you rebuild is the wrong home for those.
The one thing you cannot skip is CHATMUX_MCP_HOST. The daemon binds 127.0.0.1 by
default, which inside a container is the container's own loopback — a published port
then maps to a socket nobody is listening on, and every connection is refused while the
logs look perfectly healthy. Read deploy/container/README.md before assuming your
port mapping is broken.
Development
bun run dev # Start with --watch (auto-reload)
bun test # Run all tests
bun run start # Start daemon
See docs/ for detailed architecture and protocol documentation.
Limitations
Known and accepted, with what would make each worth revisiting.
- The chat list caps at 1000, silently.
chat://chatsis hard-coded to that limit. Consumers can detect an overflow by comparing thetotalfield against what arrived, so it will not bite you without saying so. Worth raising once a vault approaches ~500 chats, or the first time that completeness check fires. - The JSONL log holds duplicate history. Backfill re-ingested some messages many times over, leaving the event log several times larger than the messages in it. This has stopped: recent growth is almost entirely new distinct messages, and the worst-case duplicate count has been frozen across repeated measurements. It is not a correctness problem — ingestion is idempotent and the SQLite projection is unaffected — so the fix, if ever needed, is a one-off compaction rather than a code change. Worth doing if the log passes ~500 MB, if the duplicate count starts climbing again, or if cold start slows noticeably.
- Retractions in Telegram one-to-one chats are missed. Group retractions land; direct ones do not, because the adapter cannot recover the chat id for those events from its entity cache, and core will not match a message on id alone — that ambiguity is exactly what the storage key was widened to remove. So a message you retracted on your phone can stay visible here. Worth fixing once the adapter can resolve the chat id itself, or as soon as retraction accuracy matters to a consumer.
- Reactions are not stored at all. The platforms send them; no layer reads them. Nothing in core, the schema, or the MCP surface represents a reaction, so a consumer cannot show what a phone shows. Worth building when reactions carry meaning you would otherwise miss — it is new storage, not a display tweak.
read_receiptis declared but never emitted. The LINE adapter advertises the capability and core is ready to ingest it; nothing constructs the event. Whether read state should reach a UI at all is an open product question, not a pending bug — but the declaration is wrong today, so do not branch onsupported_eventsfor this one. Worth fixing as soon as any consumer does branch on it, or once that product question gets an answer.
⚠️ Account Risk Warning
This project uses @evex/linejs, an unofficial LINE client library. Using unofficial APIs may violate LINE's Terms of Service. Your LINE account may be restricted, suspended, or permanently banned. Use at your own risk.
The IOSIPAD device slot is used to avoid interfering with your phone's LINE app, but LINE may change their multi-device policy at any time.
⚠️ Legal Disclaimer
This software is provided "as is", without warranty of any kind. The author is not responsible for any consequences of using this software, including but not limited to account restrictions, data loss, or violations of third-party terms of service.
This is a personal tool for personal use. Do not use it for spam, harassment, unauthorized access to others' messages, or any illegal activity.
🔒 Privacy Disclosure
chatmux stores decrypted message content in plaintext on your local machine:
~/.local/share/chatmux/events.jsonl— all events (append-only)~/.local/share/chatmux/chatmux.db— SQLite database with messages, contacts, chats~/.local/share/chatmux/adapters/line/auth.json— LINE auth token~/.local/share/chatmux/adapters/line/storage.json— E2EE key storage
These files are protected by filesystem permissions (owner-only). Do not share these files. The auth token grants full access to your LINE account. The E2EE keys can decrypt your messages.
v0.1 does not encrypt the database. SQLCipher encryption is planned for v0.2.
License
MIT
chatmux MCP questions
What tools does chatmux MCP provide?
It exposes 8 tools, including list_chats, read_messages, read_events, search_messages, send_message.
What are the risks of using the LINE adapter?
Using unofficial libraries like @evex/linejs may violate LINE's Terms of Service and could lead to account suspension or bans.