arcade-matter-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@arcade-matter-mcp search my Matter library for articles on climate and show my highlights"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
arcade-matter-mcp
An MCP server for Matter, the read-later app, built with
arcade-mcp, hosted on Arcade Cloud via
arcade deploy, and used through Arcade MCP Gateways.
It wraps Matter's public API so agents can search your library, read articles and highlights, save links, and organize your queue. See docs/SPEC.md for the full design.
Single user. Matter only offers personal API tokens (no OAuth), and Arcade secrets are shared across a project. Everyone who can call this server acts on the token owner's library, so keep its gateway to yourself.
Tools
Phase 1 (read-only):
Tool | What it does |
| The connected Matter account and its API rate limits |
| Items in the queue, inbox or archive, filtered by favorite, tag, type or date |
| One item's metadata |
| An item's full text as Markdown, in bounded chunks |
| Full-text search with |
| Highlights and notes on one item |
| Tags and how many items each is on |
| Reading sessions with start time and duration |
Phase 2 (writes):
Tool | What it does |
| Save a public URL to the queue or archive (have your client approve each URL) |
| Archive or re-queue, favorite, or set reading progress |
| Tag or untag an item (tags are created by name) |
| Rename a tag everywhere |
| Add, change or clear a highlight's note |
| Permanent deletes (destructive) |
Phase 3 (summaries, read-only):
Tool | What it does |
| An item with all its highlights and notes |
| Highlights made or edited recently, grouped by item |
| Reading time totals, averages, streaks and busiest day for a period |
Every tool is tagged read-only or write (and delete tools as destructive), so a gateway can expose only the read tools. The server can't enforce approval for writes itself, so use a read-only gateway day to day and a separate, approval-gated one for writes (see Deploy).
Related MCP server: Instapaper MCP Server
Setup
Get a Matter API token (needs Matter Pro) at web.getmatter.com/settings → Generate API Token. Generating a token revokes any previous one, so reuse an existing token if another tool (such as
matter-cli) already has it.Create
.envif you don't have one, make it readable only by you, then setMATTER_API_TOKENin it:[ -f .env ] || cp .env.example .env # never overwrites an existing .env chmod 600 .env ls -l .env # should show -rw------- (mode 0600)Already have a
.env? Just runchmod 600 .env. Copying.env.exampleover it would replace your token with the placeholder.cpgives a new copy.env.example's mode (0644, readable by other local users), so thechmodis needed either way..envis Git-ignored; never commit it, and never paste the token into issues, tasks, logs or chat.
Development
uv tool install arcade-mcp # Arcade CLI
uv sync --extra dev # project and dev dependencies
uv run pytest # unit tests (Matter is mocked; no network)
uv run ruff check . && uv run ruff format --check . && uv run mypy srcTool-selection evals (need an LLM API key; they don't call Matter):
ANTHROPIC_API_KEY=... uv run arcade evals evals/ -p anthropicTo try the tools against your own library locally, run the server over stdio (Arcade's local HTTP transport doesn't serve tools that need secrets):
uv run src/arcade_matter/server.py # stdio
(cd src/arcade_matter && arcade configure claude -n matter) # add it to Claude DesktopDeploy
arcade login
arcade deploy -e src/arcade_matter/server.py # uploads MATTER_API_TOKEN from .envRotate the token later without redeploying:
arcade secret set MATTER_API_TOKEN=mat_...Then create two MCP Gateways in the Arcade dashboard, both in Arcade Auth mode:
a read-only gateway with only the read tools, for everyday use;
a write-only gateway with the write tools you want (and the delete tools only if you need them), connected only through a client that asks you to approve every call to it. That client also connects the read-only gateway to look up IDs.
Connect a client with, for example, arcade connect claude-code --gateway <slug>. See
docs/security/gateways.md for the tool lists, client
settings and how to check the read connection can't change anything.
Security
Never commit tokens or personal library data. Keep .env readable only by you
(chmod 600 .env). Tests use invented data only. The token is held by Arcade and injected
per request; it is never exposed to the model.
Asking the model to confirm before a write is advice, not a safeguard. The safeguards are the read-only gateway and client-enforced approval for writes; see docs/security/.
License
Available Tools
20 toolsMatter_AddTagAddTagAIdempotent
Tag an item by tag name, creating the tag if it doesn't exist yet.
Inputs: name (required), item_id (required). Returns: object
Matter_DeleteHighlightDeleteHighlightADestructiveIdempotent
Permanently delete a highlight and its note. This can't be undone.
Inputs: highlight_id (required). Returns: object
Matter_DeleteItemDeleteItemADestructiveIdempotent
Permanently delete an item from the user's Matter library, along with its highlights. Its tags are only removed from this item; the tags themselves are kept (use DeleteTag to delete a tag). This can't be undone; to keep it out of the queue, archive it with UpdateItem instead.
Inputs: item_id (required). Returns: object
Matter_DeleteTagDeleteTagADestructiveIdempotent
Permanently delete a tag and remove it from every item. The items are kept. This can't be undone; to untag a single item, use RemoveTag instead.
Inputs: tag_id (required). Returns: object
Matter_GetAccountGetAccountARead-onlyIdempotent
Get the Matter account the server is connected to, including its API rate limits (requests per minute for reads, writes, saves, searches and full-text fetches) and how many read requests are left in the current window.
Inputs: no named parameters. Returns: object
Matter_GetItemGetItemARead-onlyIdempotent
Get a single item's metadata by ID. Use GetItemContent for the full text.
Inputs: item_id (required). Returns: object
Matter_GetItemContentGetItemContentARead-onlyIdempotent
Get an item's full text as Markdown, in chunks of up to max_chars. Matter allows only 20 full-text fetches per minute, so use excerpts from ListItems or GetItem when they're enough.
Inputs: item_id (required), offset, max_chars. Returns: object
Matter_GetItemWithHighlightsGetItemWithHighlightsARead-onlyIdempotent
Get an item together with every highlight and note on it (up to 100), in two requests. Use this to answer "what did I highlight in this article?".
Inputs: item_id (required). Returns: object
Matter_ListHighlightsListHighlightsBRead-onlyIdempotent
List the passages the user highlighted in one item, with any notes they added.
Inputs: item_id (required), limit, cursor. Returns: object
Matter_ListItemsListItemsARead-onlyIdempotent
List items in the user's Matter library, filtered by status, favorites, tags or content type. Use SearchLibrary to find items by words in their text, title, author or site.
Inputs: limit, order, cursor, status, +4 more. Returns: object
Matter_ListReadingSessionsListReadingSessionsBRead-onlyIdempotent
List the user's reading sessions, newest first. Each session is one period of reading with its start time and duration in seconds; a day can have several.
Inputs: limit, since, cursor. Returns: object
Matter_ListRecentHighlightsListRecentHighlightsARead-onlyIdempotent
List the highlights the user made recently, grouped by item. Use this to answer "what did I highlight this week?". Makes one request for recently updated items and one per item checked (at most 21 requests). Reading progress and tag changes also count as updates, so when more_items is set, some highlighted items may not have been checked.
Inputs: since, max_items. Returns: object
Matter_ListTagsListTagsBRead-onlyIdempotent
List the user's Matter tags with how many items each one is on.
Inputs: limit, cursor. Returns: object
Matter_RemoveTagRemoveTagAIdempotent
Remove a tag from one item. The tag itself and its other items are kept.
Inputs: tag_id (required), item_id (required). Returns: object
Matter_RenameTagRenameTagBIdempotent
Rename a tag everywhere it's used.
Inputs: name (required), tag_id (required). Returns: object
Matter_SaveItemSaveItemAIdempotent
Save a URL to the user's Matter library. Matter extracts the content in the background, usually within a minute; check GetItem later if processing_status is 'processing'. If the URL is already saved, the existing item is returned unchanged with already_in_library: true; use UpdateItem to move it.
Inputs: url (required), status. Returns: object
Matter_SearchLibrarySearchLibraryARead-onlyIdempotent
Search the user's Matter library by full text, title, author or site, ranked by relevance. Results marked in_library: false aren't saved, so item tools can't use them.
Inputs: query (required), limit, scope, cursor. Returns: object
Matter_SetHighlightNoteSetHighlightNoteAIdempotent
Add, replace or remove the note on a highlight. Matter's API can't create highlights.
Inputs: note (required), highlight_id (required). Returns: object
Matter_SummarizeReadingTimeSummarizeReadingTimeARead-onlyIdempotent
Summarize how much the user read over a period: total and average minutes, days read, the longest streak, the busiest day, and the current streak when the period reaches yesterday or today. Use this to answer "how much have I read this month?" or "how much did I read in September?". Makes up to 10 requests.
Inputs: since, until, timezone_name. Returns: object
Matter_UpdateItemUpdateItemAIdempotent
Archive or re-queue an item, favorite or unfavorite it, or set its reading progress. Pass at least one change.
Inputs: item_id (required), status, favorite, progress_percent. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools target distinct resource+action pairs (tags, items, highlights, sessions). However, ListHighlights, ListRecentHighlights, and GetItemWithHighlights all return highlights and could be confused, though descriptions clarify per-item vs cross-item scope. GetItem vs GetItemContent vs GetItemWithHighlights are also close but distinguishably described.
Every tool uses the Matter_ prefix with a consistent PascalCase verb_noun pattern (GetItem, ListTags, AddTag, RemoveTag, DeleteItem, SearchLibrary). No mixing of conventions.
20 tools is on the heavier side but justified by a genuinely multi-resource domain (items, highlights, tags, sessions, account, summaries). Each tool earns its place with minimal redundancy.
Covers full lifecycle for tags (add/remove/rename/delete/list) and strong coverage for items and highlights, plus search, sessions, account, and reading stats. Highlight creation is absent, but that is an explicit upstream API limitation rather than a design gap.
Maintenance
Related MCP Connectors
Read-it-later for AI agents. Save links, bookmarks, notes, and videos as Markdown and search them.
Access and search Branch's official API documentation directly within any AI agent or client.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
All your bookmarks in one library. Share them with your AI agents. Read-only search over your saves.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude to interact with the Readwise Reader API, allowing for saving, listing, updating, and deleting documents with complete metadata and content access through natural language.647MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude and other MCP clients to manage Instapaper accounts by reading, saving, organizing, and analyzing articles through natural language. It supports comprehensive bookmark management, bulk operations, folder organization, and full-text content retrieval for research and synthesis.27MIT
- AlicenseNot gradedqualityCmaintenanceExposes Readwise and Reader operations as MCP tools, enabling AI agents to save URLs, search documents, retrieve full content and highlights, and manage tags and locations.MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to search, browse, and cite articles from a curated reading list through read-only tools for substring search, recent listing, full article retrieval, and theme summaries.-