Skip to main content
Glama
arcade-matter-mcp

arcade-matter-mcp

by laughnan

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

Matter.GetAccount

The connected Matter account and its API rate limits

Matter.ListItems

Items in the queue, inbox or archive, filtered by favorite, tag, type or date

Matter.GetItem

One item's metadata

Matter.GetItemContent

An item's full text as Markdown, in bounded chunks

Matter.SearchLibrary

Full-text search with "phrase", -term, by:, site: and title:

Matter.ListHighlights

Highlights and notes on one item

Matter.ListTags

Tags and how many items each is on

Matter.ListReadingSessions

Reading sessions with start time and duration

Phase 2 (writes):

Tool

What it does

Matter.SaveItem

Save a public URL to the queue or archive (have your client approve each URL)

Matter.UpdateItem

Archive or re-queue, favorite, or set reading progress

Matter.AddTag / Matter.RemoveTag

Tag or untag an item (tags are created by name)

Matter.RenameTag

Rename a tag everywhere

Matter.SetHighlightNote

Add, change or clear a highlight's note

Matter.DeleteItem / Matter.DeleteHighlight / Matter.DeleteTag

Permanent deletes (destructive)

Phase 3 (summaries, read-only):

Tool

What it does

Matter.GetItemWithHighlights

An item with all its highlights and notes

Matter.ListRecentHighlights

Highlights made or edited recently, grouped by item

Matter.SummarizeReadingTime

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

  1. 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.

  2. Create .env if you don't have one, make it readable only by you, then set MATTER_API_TOKEN in 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 run chmod 600 .env. Copying .env.example over it would replace your token with the placeholder. cp gives a new copy .env.example's mode (0644, readable by other local users), so the chmod is needed either way. .env is 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 src

Tool-selection evals (need an LLM API key; they don't call Matter):

ANTHROPIC_API_KEY=... uv run arcade evals evals/ -p anthropic

To 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 Desktop

Deploy

arcade login
arcade deploy -e src/arcade_matter/server.py    # uploads MATTER_API_TOKEN from .env

Rotate 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

MIT

Available Tools

20 tools
Matter_AddTagAddTagA
Idempotent

Tag an item by tag name, creating the tag if it doesn't exist yet.

Inputs: name (required), item_id (required). Returns: object

Matter_DeleteHighlightDeleteHighlightA
DestructiveIdempotent

Permanently delete a highlight and its note. This can't be undone.

Inputs: highlight_id (required). Returns: object

Matter_DeleteItemDeleteItemA
DestructiveIdempotent

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_DeleteTagDeleteTagA
DestructiveIdempotent

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_GetAccountGetAccountA
Read-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_GetItemGetItemA
Read-onlyIdempotent

Get a single item's metadata by ID. Use GetItemContent for the full text.

Inputs: item_id (required). Returns: object

Matter_GetItemContentGetItemContentA
Read-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_GetItemWithHighlightsGetItemWithHighlightsA
Read-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_ListHighlightsListHighlightsB
Read-onlyIdempotent

List the passages the user highlighted in one item, with any notes they added.

Inputs: item_id (required), limit, cursor. Returns: object

Matter_ListItemsListItemsA
Read-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_ListReadingSessionsListReadingSessionsB
Read-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_ListRecentHighlightsListRecentHighlightsA
Read-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_ListTagsListTagsB
Read-onlyIdempotent

List the user's Matter tags with how many items each one is on.

Inputs: limit, cursor. Returns: object

Matter_RemoveTagRemoveTagA
Idempotent

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_RenameTagRenameTagB
Idempotent

Rename a tag everywhere it's used.

Inputs: name (required), tag_id (required). Returns: object

Matter_SaveItemSaveItemA
Idempotent

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_SearchLibrarySearchLibraryA
Read-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_SetHighlightNoteSetHighlightNoteA
Idempotent

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_SummarizeReadingTimeSummarizeReadingTimeA
Read-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_UpdateItemUpdateItemA
Idempotent

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

    A3.9/5.0

    Scored across 20 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    Every tool uses the Matter_ prefix with a consistent PascalCase verb_noun pattern (GetItem, ListTags, AddTag, RemoveTag, DeleteItem, SearchLibrary). No mixing of conventions.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      6
      47
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      27
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes 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
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -