Skip to main content
Glama
Thoughts Connector

Thoughts Connector

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; uvicorn comes with mcp).

  • 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 connector on the server host.

  • thoughts_cli (the headless proposal client, clients/thoughts-cli/thoughts_cli in the thoughts-server repository) next to thoughts_connector.py, or THOUGHTS_CLI pointing at it.

  • For send_note: agent_notes.py from the Thoughts desktop repository (tools/mcp/agent_notes.py) next to thoughts_connector.py or at THOUGHTS_AGENT_NOTES, and Chromium or Google Chrome (THOUGHTS_CHROME).

  • import_pdf, merge_review_cards and pending card moves need a Thoughts server that announces the capabilities library_import_pdf_v1, review_card_merge_v1 and review_card_pending_moves_v1, and a thoughts-cli with merge-review-cards and pending card moves; without them the tools answer not_supported.

  • Moving a card linked to source markers needs review_card_move_pairs_v1 and thoughts-cli 1.7.0 (move-card-passage); without them move_review_card answers server_unsupported or not_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 need agent_note_claims_v1, agent_note_owners_v1 and agent_note_rules_v1.

Configuration

Variable

Default

Meaning

CONNECTOR_PUBLIC_URL

https://thoughts.example.org

public origin of the reverse proxy (the connector lives under /connector)

CONNECTOR_PASSPHRASE

~/connectors/passphrase.json

scrypt hash of the sign-in passphrase

THOUGHTS_URL

http://127.0.0.1:8080

the Thoughts server

THOUGHTS_CONNECTOR_TOKEN

~/connectors/thoughts-token

file with the connector's device token

THOUGHTS_CONNECTOR_STATE

~/connectors/state/thoughts

OAuth clients, hashed tokens, request records

THOUGHTS_CONNECTOR_PORT

8095

loopback port

THOUGHTS_CLI

the connector's folder

where thoughts_cli is

THOUGHTS_AGENT_NOTES

agent_notes.py next to the connector

the note renderer

THOUGHTS_CHROME

see agent_notes.py

Chromium/Chrome for rendering notes

THOUGHTS_DIARY_AUTHOR

user

author name written on diary entries

THOUGHTS_DIARY_ZONE

Europe/Zurich

time zone of diary entries and of "this week" in knowledge_profile

THOUGHTS_AGENT_CONVERSATION

empty

for a connector process that serves one agent session: the conversation send_note and get_note use when the call names none

THOUGHTS_NOTE_ORIGIN

{}

JSON object of extra origin fields for every note this process sends

THOUGHTS_RULES_IN_PROMPT

unset

1: the agent has the answering rules in its prompt, so get_note names them instead of repeating them

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 tests

Set 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      3
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      -