nextcloud MCP server
Commit Oct 14, 2026Exposes Nextcloud News accounts to MCP clients to browse feeds, read articles, and manage read, unread, and starred states.
Also known as mrdev023/mcp-nextcloud
- Stars
- 0
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 14, 2026
- License
- MIT
What is nextcloud MCP?
nextcloud exposes Nextcloud News accounts to MCP clients to browse feeds, read articles, and manage read, unread, and starred states. It exposes 7 tools, such as news_list_feeds, news_list_items, news_get_item.
Summary generated from the project's README
About nextcloud MCP server
Managing RSS feeds and reading news articles directly from an AI assistant is what mcp-nextcloud enables. This Go-based server connects MCP clients like Claude Desktop, Claude Code, or Cursor to a Nextcloud News account. It allows users to browse various feeds, read full article text, and control the status of their content by marking items as read, unread, or starred.
Users can deploy the server using a single static binary or via Docker. It supports two distinct authentication methods: a standalone mode that uses an app-password and an embedded OAuth 2.1 server, or an OIDC mode for integration with external providers like Keycloak. The server operates via streamable HTTP on a specific endpoint and maintains a small footprint of approximately 15 MB of RAM.
Developers can restrict the server to read-only operations by setting a specific environment variable. The available tools include news_list_feeds for browsing, news_get_item for retrieving article bodies, and news_mark_read for updating article states. This setup provides a lightweight way to bring personal news aggregators into an AI-driven workflow.
What you can do with it
- 1Summarize unread news articlesAsk your AI agent to read all unread RSS articles and provide a concise summary of the latest news.
- 2Manage article reading statusInstruct your client to mark specific articles or all recent items as read after processing them.
Written from the project's README. Every use case is checked against a quote from it.
nextcloud MCP tools 7
Detected from the READMEnews_list_feedsnews_list_itemsnews_get_itemnews_mark_readnews_mark_unreadnews_mark_all_readnews_get_updated
Configuration
CGO_ENABLEDMCP_AUTH_PASSWORDNEXTCLOUD_APP_PASSWORDNEXTCLOUD_URLNEXTCLOUD_USER
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 reachablemrdev023/mcp-nextcloud is public and reachablegithub.com/mrdev023/mcp-nextcloud ↗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-10-14github.com/mrdev023/mcp-nextcloud ↗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 model7 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 GitHubmcp-nextcloud
[!WARNING] Work in progress — do not use in production. This is a personal project under active development: its configuration, tools and behaviour can change at any time without notice. It is provided as is, without any warranty (see the license); I accept no responsibility for any damage, data loss or security issue resulting from its use. If you run it anyway, do so at your own risk.
An MCP server, written in Go, that exposes a Nextcloud News account to MCP clients (Claude Code, Claude Desktop, Cursor, …). It lets them browse feeds and articles, read full text, and manage read / unread and starred state.
- Transport. Streamable HTTP on
/mcp. - Two authentication modes, both following the MCP authorization spec:
standalone(default). No identity provider is needed. mcp-nextcloud embeds a small OAuth 2.1 server and calls Nextcloud with an app-password that never leaves the server.oidc. An external OpenID Connect provider (Keycloak, …) issues the tokens. mcp-nextcloud validates them and obtains a separate Nextcloud token per user through token exchange.
- Small footprint. A single static binary (~11 MB) using ~15 MB of RAM, built from the standard library plus the official Go MCP SDK.
flowchart LR
C[MCP client] -- "OAuth bearer token" --> M[mcp-nextcloud]
M -- "standalone: app-password<br/>oidc: exchanged per-user token" --> N[Nextcloud News]
M -. "oidc only: JWKS, token exchange" .-> P[OIDC provider]
Real-world use. I run mcp-nextcloud in OIDC mode behind agentgateway, with Keycloak as the identity provider. My AI agent uses it to read the unread RSS articles, write a summary of them, and mark them as read.
This is also how the project is tested: I test it continuously on my own infrastructure, with that agent as its real user. That covers one personal setup only, and is no guarantee that it works elsewhere.
Quick start
Run mcp-nextcloud in standalone mode:
export NEXTCLOUD_URL=https://cloud.example.com
export NEXTCLOUD_USER='your-user'
export NEXTCLOUD_APP_PASSWORD='xxxxx-xxxxx-xxxxx-xxxxx-xxxxx' # Nextcloud: Settings → Security
export MCP_AUTH_PASSWORD='a long passphrase' # typed when a client asks for access
go run github.com/mrdev023/mcp-nextcloud/cmd/mcp-nextcloud@latest
Then connect a client, for example Claude Code:
claude mcp add --transport http nextcloud http://localhost:8080/mcp
# then in Claude Code: /mcp → nextcloud → Authenticate
Or with Docker. Multi-arch images are published on GHCR; they are distroless, run as non-root and are about 5 MB compressed:
docker run -d -p 8080:8080 \
-e NEXTCLOUD_URL=https://cloud.example.com -e NEXTCLOUD_USER='your-user' \
-e NEXTCLOUD_APP_PASSWORD='xxxxx-xxxxx-xxxxx-xxxxx-xxxxx' -e MCP_AUTH_PASSWORD='a long passphrase' \
ghcr.io/mrdev023/mcp-nextcloud:latest
Documentation
| Guide | |
|---|---|
| Standalone mode | App-password setup, Docker Compose, reverse proxy, client configuration, OAuth flow |
| OIDC mode | External identity provider, token validation and exchange, direct or gateway deployments |
| Keycloak example | Clients, audience mappers and Nextcloud user_oidc settings, step by step |
| Configuration reference | Every environment variable and HTTP endpoint |
| Architecture | Code layout, request lifecycle, design choices, tests, build |
| Troubleshooting | Common errors and their fixes |
Tools
| Tool | What it does | Hints |
|---|---|---|
news_list_feeds |
Feeds (id, title, url, folder, unread count) and folders | read-only |
news_list_items |
Articles, unread only by default. Filters: feedId, folderId, starredOnly, includeRead, search; paging: limit (≤ 100), offset, oldestFirst; includeBody |
read-only |
news_get_item |
One article: title, url, author, body (format text or html, maxBodyChars) |
read-only |
news_mark_read |
Mark itemId or itemIds[] as read |
idempotent, reversible |
news_mark_unread |
Mark itemId or itemIds[] as unread |
idempotent, reversible |
news_mark_all_read |
Mark everything read up to newestItemId (default: the newest article) |
idempotent, destructive |
news_star / news_unstar |
Star / unstar an article (id) |
idempotent, reversible |
news_get_updated |
Incremental sync since lastModified; returns nextLastModified |
read-only |
- Pagination. In the News API,
offsetis an article id, not a count. Pass back thenextOffsetreturned by the previous page;nextOffset: 0means there are no more pages. - Bodies. List tools return a 280-character excerpt, or the body truncated to 2,000 characters with
includeBody.news_get_itemreturns plain text truncated to 20,000 characters by default. - Read-only mode. With
MCP_READ_ONLY=true, only the four read-only tools are exposed: the server can browse articles but never change their state.
Development
go test ./...
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o mcp-nextcloud ./cmd/mcp-nextcloud
An optional Nix shell (shell.nix) provides Go, gopls and golangci-lint; with direnv, run direnv allow. See Architecture for how the code is organised.
Need more than News?
For now this project covers Nextcloud News only, in a small Go binary; it was renamed from mcp-nextcloud-news because support for more Nextcloud apps is planned. If you need an MCP server for the rest of your Nextcloud today, have a look at cbcoutinho/nextcloud-mcp-server. It is an excellent, much more complete project, covering:
- Notes, Calendar, Contacts, Files, Deck, Tables, Cookbook and News, among other apps;
- multi-user authentication;
- optional semantic search.
Many thanks to its author; it was a great reference while building this one.
License
nextcloud MCP questions
What tools does nextcloud MCP provide?
It exposes 7 tools, including news_list_feeds, news_list_items, news_get_item, news_mark_read, news_mark_unread.
What is the resource footprint of the server?
The server is very lightweight, consisting of a single 11 MB static binary that uses approximately 15 MB of RAM.