Thoughts Connector
Integrates with the Thoughts Android app on the user's phone to send notes, read replies including drawings and photos, and show whether an agent is listening for replies.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Thoughts connector
An MCP server that lets ChatGPT and Claude (web, desktop and phone apps) work with a Thoughts Library (the Thoughts server and its desktop and Android apps): read and search documents, see review cards and the passages the user liked or disliked, send notes to the phone, and suggest edits as agent proposals that the user accepts or rejects in the Thoughts apps.
It runs next to a Thoughts server, behind an HTTPS reverse proxy, and is its own OAuth 2.1 authorization server: the user connects it once in ChatGPT or Claude and signs in with a passphrase.
By Tommaso Bendinelli.
What it can do
Tools: list_documents (with each PDF's Library filename), read_document (LaTeX with \input
files inlined, Markdown, or PDF text), search_library, document_feedback, review_cards /
get_review_card, knowledge_profile (which cards on a topic are solid, shaky, unknown or
unreviewed), link_conversation, list_notes, get_note (with the user's replies, their drawings
and the photo sent with a reply), send_note (Markdown with math rendered to a phone-width PNG; its
links become tappable areas of the picture that open a web page or a page of a Library PDF),
note_rules, own_topic / release_topic, add_diary_entry, read_source,
create_proposals / revise_proposal / remove_proposal, source_conflicts /
read_source_conflict / resolve_source_conflict, create_document, create_review_card /
move_review_card (a card linked to source markers moves with its marked passage as two linked
pending proposals that the user accepts or rejects as one), merge_review_cards (cards of one
document merged into one, when the user asks), pending_card_moves / cancel_pending_card_move (a
card moved onto the text of a pending proposal waits until the user accepts that proposal),
html_pages / add_html_page, build_status, move_pdf, import_pdf (the server downloads a PDF
from a URL into a Project).
Reply listening: while get_note waits for a reply (wait_for_reply_s), or while
thoughts-watch-replies runs, the server knows that an agent listens, and the phone shows the user
whether their reply will be heard; send_note says when nobody listens.
Who answers a reply (thoughts-server protocol/agent-notes.md, "Who answers"): an agent passes its
conversation id to send_note and get_note; get_note then claims each reply (or the page the user
sent) that the conversation covers, so only one agent answers it, and hands over the user's answering
rules (the Library note agent-note-rules.md, also read by note_rules). own_topic makes a
conversation responsible for the notes and pages of a topic (a Project, documents, review cards or
title tags) while it keeps thoughts-watch-replies --conversation <id> running; release_topic ends
it. What no running agent covers is left to a responder agent, if the server's owner runs one
("One responder"); it is not part of this repository. The tool texts name the watcher as
~/.local/bin/thoughts-watch-replies, so install it there.
The connector talks to the Thoughts server as its own device (connector), and every request goes
through an allowlist in thoughts_connector.py (check_request): it reads the Library, creates
agent notes, diary entries and conversation links, claims replies, registers and ends topic owners,
reads the answering rules, publishes sources into which thoughts-cli wrote pending proposals, and
asks the server for a PDF import by URL, a merge of review cards or a pending card move. It never
accepts or rejects a proposal and never reviews or retires a card; cards are deleted only by the
server, as part of a merge the user asked for. It refuses every other Library-project action.
Related MCP server: reMarkable MCP Server
Requirements
Python 3.11+ with the packages in
requirements.txt(mcp,pypdf,httpx;uvicorncomes withmcp).A Thoughts server reachable from the connector (default
http://127.0.0.1:8080) and a device token for the connector:thoughts-admin create-device connectoron the server host.thoughts_cli(the headless proposal client,clients/thoughts-cli/thoughts_cliin the thoughts-server repository) next tothoughts_connector.py, orTHOUGHTS_CLIpointing at it.For
send_note:agent_notes.pyfrom the Thoughts desktop repository (tools/mcp/agent_notes.py) next tothoughts_connector.pyor atTHOUGHTS_AGENT_NOTES, and Chromium or Google Chrome (THOUGHTS_CHROME).import_pdf,merge_review_cardsand pending card moves need a Thoughts server that announces the capabilitieslibrary_import_pdf_v1,review_card_merge_v1andreview_card_pending_moves_v1, and a thoughts-cli withmerge-review-cardsand pending card moves; without them the tools answernot_supported.Moving a card linked to source markers needs
review_card_move_pairs_v1and thoughts-cli 1.7.0 (move-card-passage); without themmove_review_cardanswersserver_unsupportedornot_supported.Links in notes need
agent_note_links_v1(otherwise the note is sent without them, with a warning); claims, topic owners and answering rules needagent_note_claims_v1,agent_note_owners_v1andagent_note_rules_v1.
Configuration
Variable | Default | Meaning |
|
| public origin of the reverse proxy (the connector lives under |
|
| scrypt hash of the sign-in passphrase |
|
| the Thoughts server |
|
| file with the connector's device token |
|
| OAuth clients, hashed tokens, request records |
|
| loopback port |
| the connector's folder | where |
|
| the note renderer |
| see | Chromium/Chrome for rendering notes |
|
| author name written on diary entries |
|
| time zone of diary entries and of "this week" in |
| empty | for a connector process that serves one agent session: the conversation |
|
| JSON object of extra |
| unset |
|
Running it
python3 -m venv venv && venv/bin/pip install -r requirements.txt
venv/bin/python thoughts_connector.py set-passphrase # prints a new passphrase once
venv/bin/python thoughts_connector.py serve # or install thoughts-connector.service (systemd --user)Other commands: status (connected clients), revoke-all (disconnect every client and browser).
The reverse proxy must forward /connector/* and the OAuth discovery documents
/.well-known/oauth-protected-resource/connector/mcp and
/.well-known/oauth-authorization-server/connector (and the openid-configuration spellings) to
127.0.0.1:8095. With Caddy:
thoughts.example.org {
@connector path /connector /connector/* /.well-known/oauth-protected-resource/connector/* /.well-known/oauth-authorization-server/connector /.well-known/openid-configuration/connector
reverse_proxy @connector 127.0.0.1:8095
}thoughts-watch-replies is an optional monitor for agents that run on the server host: it prints
one line per reply the phone sends to a note of the connector, and tells the server that an agent
listens. With --conversation <id> it listens only for that conversation's notes and the topics it
owns (its polls keep those ownerships alive) and prints a PAGE line for each page the user sends
on them; it starts by printing the user's answering rules (RULES| lines) when the server serves
them. It uses the connector's token and agent_notes.py (THOUGHTS_AGENT_NOTES);
thoughts-watch-replies --check tests the connection.
Then add https://<your host>/connector/mcp as a custom connector in ChatGPT or Claude.
chatgpt-plugin/thoughts/ is a plugin manifest for the same URL; replace the host in mcp.json.
Only ChatGPT and Claude redirect URIs (or a loopback port for their desktop apps) may register as OAuth clients; five wrong passphrases from one address lock the sign-in for 15 minutes.
Tests
pip install pytest
THOUGHTS_CLI=/path/to/thoughts-server/clients/thoughts-cli pytest testsSet THOUGHTS_AGENT_NOTES=/path/to/thoughts-desktop/tools/mcp/agent_notes.py to also run the tests
of thoughts-watch-replies (skipped without it).
The tests run the connector against a fake Thoughts server and check every tool end to end through
OAuth and MCP. Without THOUGHTS_CLI, they look for a thoughts-server checkout next to this one;
the proposal tools' tests are skipped when thoughts-cli is missing or too old.
Licence
GPL-2.0-or-later, like the Thoughts server and desktop app; see LICENSE and
LICENSES/GPL-2.0-or-later.txt. Third-party notices: THIRD-PARTY-NOTICES.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Personal context for every AI: search, read, and write back to your private Markdown library.
Gives your AI assistant persistent memory and intelligence about your work patterns.
Read, edit and improve shared documents and knowledge with people and agents.
Governed memory and workspace for any AI: tasks, calendar, mail and pages, with per-action consent.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to read, search, and traverse your reMarkable tablet's library, including handwritten notes via OCR.12MIT
- AlicenseAqualityAmaintenanceEnables AI assistants to read, search, and traverse your entire reMarkable library, including handwritten notes via OCR.14265MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to turn conversations into a searchable personal wiki, read and organize pages, and propose edits such as merges, translations, and fact-checks as reviewable changesets.3MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to capture bookmarks, sticky notes, todos, notes, and web archives, and to search and organize personal knowledge and memory across cloud-synced clients.-