Skip to main content
Glama
collectives-mcp

collectives-mcp

by megamaced

collectives-mcp

A Model Context Protocol server for Nextcloud Collectives — exposes collectives, pages, tags, attachments, templates, public shares, page history, and trash to Claude and any MCP-compatible client.

How it works

The server uses two Nextcloud APIs, verified against the Collectives OpenAPI spec:

Layer

Used for

OCS API (/ocs/v2.php/apps/collectives/api/v1.0/...)

All structured operations: collectives, pages, tags, attachments, shares, settings, trash, templates, search, favorites

WebDAV (/remote.php/dav/files/{user}/...)

Page and template body read/write (no OCS equivalent), attachment upload/download, file version history

The OCS API handles structured operations and returns typed JSON. WebDAV is used only where OCS has no equivalent — primarily reading and writing page markdown content.

Related MCP server: nextcloud-collectives-mcp

Tools exposed (57)

  • Collectives: list_collectives, create_collective, update_collective, delete_collective, set_page_mode, set_user_settings

  • Collective trash: list_trashed_collectives, restore_trashed_collective, permanently_delete_collective

  • Pages: list_pages, get_page, create_page, update_page, delete_page, rename_page, move_page, move_page_to_collective, copy_page, set_page_emoji, set_page_tags, favorite_page, unfavorite_page

  • Page layout & ordering: set_page_full_width, set_subpage_order, touch_page

  • Tags: list_tags, create_tag, update_tag, delete_tag

  • Trash & history: list_trashed_pages, restore_page, purge_page, list_page_versions, restore_page_version, list_recent_pages

  • Templates: list_templates, create_template, update_template, get_template, update_template_content, set_template_emoji, delete_template

  • Search: search, search_in_collective

  • Attachments: list_attachments, get_attachment, upload_attachment, rename_attachment, delete_attachment, restore_attachment

  • Public shares: list_shares, create_collective_share, create_page_share, update_share, delete_share

  • Other: ping, get_backlinks

Every tool declares MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so clients can distinguish a read from an irreversible delete without parsing descriptions.

Install

Download the collectives-mcp-<version>.tgz asset from the latest release, then:

npm install -g ./collectives-mcp-<version>.tgz

This installs the collectives-mcp command globally.

Configuration

Add to your MCP client config (Claude Code shown):

{
  "mcpServers": {
    "collectives": {
      "command": "collectives-mcp",
      "args": [],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud.example.com",
        "NEXTCLOUD_USER": "your-username",
        "NEXTCLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Generate the app-password in Nextcloud under Settings > Security > Devices & sessions > "Create new app password". The MCP server only needs an app-password, never your real account password — and you can revoke it without affecting your main login.

Development

pnpm install
pnpm dev      # stdio MCP server, point mcp inspector at it
pnpm test     # unit tests, plus integration tests when MCP_TEST_COLLECTIVE_ID is set
pnpm build    # tsc -> dist/

Required env vars: NEXTCLOUD_URL, NEXTCLOUD_USER, NEXTCLOUD_APP_PASSWORD. Optional: NEXTCLOUD_TIMEOUT_MS (per-request deadline, default 60000).

The integration tests additionally need MCP_TEST_COLLECTIVE_ID set to the numeric id of a throwaway collective. Without it they skip; the deterministic unit tests still run.

Disclosure

This project was 100% written by AI (Claude), including all source code, tests, CI configuration, and documentation.

License

MIT — see LICENSE.

Available Tools

57 tools
copy_pageA

Duplicate a page under the same parent. If newTitle is provided, the copy gets that title. Works for both leaf and folder pages.

Inputs: pageId (required), collectiveId (required), index, newTitle.

create_collectiveA

Create a new Collective. Also creates the underlying Nextcloud Team. Optionally set an emoji icon.

Inputs: name (required), emoji.

create_collective_shareA

Create a public share link for an entire Collective. Anyone with the link can read it (and edit, if you later enable that with update_share). Returns the share token; build the URL as {nextcloud}/apps/collectives/p/{token}.

Inputs: collectiveId (required), password.

create_pageA

Create a new page under a parent. If the parent is a leaf page, it is automatically promoted to a folder. Optionally initialise from a template.

Inputs: title (required), collectiveId (required), parentPageId (required), body, +2 more.

create_page_shareA

Create a public share link for a single page rather than the whole Collective. Returns the share token; build the URL as {nextcloud}/apps/collectives/p/{token}.

Inputs: pageId (required), collectiveId (required), password.

create_tagB

Create a new tag in a Collective. Requires a name and a hex color code (e.g. "#FF0000").

Inputs: name (required), color (required), collectiveId (required).

create_templateB

Create a page template in a Collective.

Inputs: title (required), parentId (required), collectiveId (required).

delete_attachmentA
DestructiveIdempotent

Delete an attachment from a page. Returns the deleted attachment including its id, which restore_attachment needs to undo this.

Inputs: pageId (required), filename (required), collectiveId (required).

delete_collectiveA
DestructiveIdempotent

Soft-delete a Collective (moves it to the Collectives trash, recoverable). Use permanently_delete_collective to remove it permanently and optionally delete the underlying Team.

Inputs: id (required).

delete_pageA
DestructiveIdempotent

Trash a page (recoverable from the Collectives page trash). Folder pages take their entire subtree with them. The Landing page cannot be deleted — delete the collective itself instead.

Inputs: pageId (required), collectiveId (required).

delete_shareA
DestructiveIdempotent

Revoke a public share link. The link stops working immediately for everyone holding it. Pass pageId for a page share; omit it for the Collective-wide share.

Inputs: token (required), collectiveId (required), pageId.

delete_tagA
DestructiveIdempotent

Delete a tag from a Collective.

Inputs: tagId (required), collectiveId (required).

delete_templateC
DestructiveIdempotent

Delete a page template.

Inputs: templateId (required), collectiveId (required).

favorite_pageA
Idempotent

Mark a page as a favorite for the authenticated user.

Inputs: pageId (required), collectiveId (required).

get_attachmentA
Read-onlyIdempotent

Download an attachment's contents. Returns the bytes as utf8 text or a base64 string, with the encoding stated in the result. Refuses files over 5 MB, which should be fetched from Nextcloud directly.

Inputs: pageId (required), filename (required), collectiveId (required), encoding.

get_pageA
Read-onlyIdempotent

Fetch a page as markdown. Returns the metadata block followed by the page body.

Inputs: pageId (required), collectiveId (required).

get_templateA
Read-onlyIdempotent

Read a page template's metadata and markdown body. Use this to inspect what create_page(templateId) will produce.

Inputs: templateId (required), collectiveId (required).

list_attachmentsA
Read-onlyIdempotent

List attachments for a page. Returns name, size, content type, and the relative markdown path to reference each file.

Inputs: pageId (required), collectiveId (required).

list_collectivesA
Read-onlyIdempotent

List all Collectives the authenticated user has access to. Returns id, name, slug, emoji, and permission levels.

Inputs: no named parameters.

list_pagesA
Read-onlyIdempotent

List all pages in a Collective. Returns flat metadata (id, title, parentId, emoji, tags, timestamps, paths). Use parentId to reconstruct the tree.

Inputs: collectiveId (required).

list_page_versionsA
Read-onlyIdempotent

List available versions (revision history) for a page. Returns version ids that can be used with restore_page_version.

Inputs: pageId (required), collectiveId (required).

list_recent_pagesA
Read-onlyIdempotent

List recently-modified pages for a Collective, ordered by last edit time.

Inputs: collectiveId (required), limit.

list_sharesA
Read-onlyIdempotent

List all public share links on a Collective, including per-page shares. Each entry reports its scope ("collective" or "page"), token, whether visitors can edit, and whether a password is set. Passwords themselves are never returned.

Inputs: collectiveId (required).

list_tagsA
Read-onlyIdempotent

List all tags defined for a Collective.

Inputs: collectiveId (required).

list_templatesA
Read-onlyIdempotent

List page templates defined for a Collective.

Inputs: collectiveId (required).

list_trashed_collectivesA
Read-onlyIdempotent

List Collectives that have been soft-deleted. These can be restored or permanently deleted.

Inputs: no named parameters.

list_trashed_pagesA
Read-onlyIdempotent

List pages in the trash for a Collective. These can be restored or permanently purged.

Inputs: collectiveId (required).

move_pageA
Idempotent

Move a page to a new parent within the same collective. If the new parent is a leaf, it is promoted first.

Inputs: pageId (required), collectiveId (required), newParentPageId (required), index.

move_page_to_collectiveA
Destructive

Move or copy a page (with its subpages and attachments) into a different Collective. Set copy: true to duplicate instead of moving. The page id changes on arrival, so use the returned page for follow-up calls. For reorganising within one Collective use move_page or copy_page instead.

Inputs: pageId (required), collectiveId (required), newCollectiveId (required), copy, +2 more.

permanently_delete_collectiveA
DestructiveIdempotent

Permanently delete a Collective from the trash. THIS IS IRREVERSIBLE. The Collective must already be in the trash (use delete_collective first). Set deleteTeam=true to also remove the underlying Nextcloud Team.

Inputs: id (required), deleteTeam.

pingA
Read-onlyIdempotent

Verify connectivity to the configured Nextcloud instance and report how many collectives are visible.

Inputs: no named parameters.

purge_pageA
DestructiveIdempotent

Permanently delete a trashed page. THIS IS IRREVERSIBLE — the page content cannot be recovered after this call. The page must already be in the trash (use delete_page first).

Inputs: pageId (required), collectiveId (required).

rename_attachmentA
Idempotent

Rename an attachment on a page. Existing references to the old filename in page bodies are NOT rewritten — update them yourself, using the returned relativePath.

Inputs: pageId (required), newName (required), filename (required), collectiveId (required).

rename_pageB
Idempotent

Rename a page within its current parent.

Inputs: pageId (required), newTitle (required), collectiveId (required).

restore_attachmentA
Idempotent

Restore a deleted attachment from the page's attachment trash. Takes the numeric attachment id — a trashed attachment no longer appears in list_attachments, so there is no name to look up. delete_attachment returns the id you need.

Inputs: pageId (required), attachmentId (required), collectiveId (required).

restore_pageB
Idempotent

Restore a trashed page back to its original location.

Inputs: pageId (required), collectiveId (required).

restore_page_versionA
DestructiveIdempotent

Restore a specific historical version of a page. The current content is replaced with the selected version (the current version is preserved as a new version entry).

Inputs: pageId (required), versionId (required), collectiveId (required).

restore_trashed_collectiveA
Idempotent

Restore a soft-deleted Collective from the trash.

Inputs: id (required).

search_in_collectiveA
Read-onlyIdempotent

Search for pages by content within a specific Collective. Returns matching page metadata.

Inputs: query (required), collectiveId (required).

set_page_emojiA
Idempotent

Set the single-emoji icon on a page. Pass an empty string to clear.

Inputs: emoji (required), pageId (required), collectiveId (required).

set_page_full_widthA
Idempotent

Toggle a page's full-width layout. This is a Collective-wide display property of the page, not a per-user preference.

Inputs: pageId (required), fullWidth (required), collectiveId (required).

set_page_modeA
Idempotent

Set the default page mode for a Collective — whether pages open in view or edit mode. This applies to every member of the Collective, unlike set_user_settings which is per-user.

Inputs: mode (required), collectiveId (required).

set_page_tagsA
DestructiveIdempotent

Replace the tags on a page. Tags must already exist in the Collective; pass tag ids (use list_tags to look them up).

Inputs: pageId (required), tagIds (required), collectiveId (required).

set_subpage_orderA
Idempotent

Set the explicit left-to-right ordering of a page's immediate child pages. Every id must be a direct child of the page; duplicates are rejected. Pass an empty array to clear the manual order and fall back to the Collective sort. Only takes effect for users whose page order is set to "byOrder".

Inputs: pageId (required), collectiveId (required), subpageOrder (required).

set_template_emojiA
Idempotent

Set or clear the emoji icon on a page template.

Inputs: emoji (required), templateId (required), collectiveId (required).

set_user_settingsA
Idempotent

Update the authenticated user's own display preferences for one Collective: page sort order, and whether the members and recent-pages widgets on the landing page are expanded. These are per-user and do not affect other members — use set_page_mode for the Collective-wide setting. Provide at least one field; omitted fields are left unchanged.

Inputs: collectiveId (required), pageOrder, showMembers, showRecentPages.

touch_pageA

Bump a page's modification timestamp and record the authenticated user as its last editor, without changing content. Useful for marking a page as reviewed.

Inputs: pageId (required), collectiveId (required).

unfavorite_pageA
Idempotent

Remove a page from the authenticated user's favorites.

Inputs: pageId (required), collectiveId (required).

update_collectiveA
Idempotent

Change a Collective's emoji or adjust edit/share permission levels. Provide the id and any fields to change. Note: collective renaming is not supported by the API.

Inputs: id (required), emoji, editPermissionLevel, sharePermissionLevel.

update_pageB
Destructive

Replace, append to, or prepend to a page's markdown body. Mode defaults to "replace".

Inputs: body (required), pageId (required), collectiveId (required), mode.

update_shareA
Idempotent

Update an existing share link. editable is required by the API and is always applied, so state it explicitly or you may silently change it. Pass pageId for a page share; omit it for the Collective-wide share. Pass an empty password to remove an existing one.

Inputs: token (required), editable (required), collectiveId (required), pageId, +1 more.

update_tagA
Idempotent

Update a tag. Both name and color are always applied, so pass the existing value for whichever one you are not changing — omitting a field is not supported by the API. Read current values with list_tags first.

Inputs: name (required), color (required), tagId (required), collectiveId (required).

update_templateB
Idempotent

Rename a page template.

Inputs: title (required), templateId (required), collectiveId (required).

update_template_contentA
Destructive

Write a page template's markdown body. This is the content create_page(templateId) copies into new pages. An empty body is allowed and clears the template. Append and prepend are protected against concurrent edits and fail rather than overwriting someone else's change.

Inputs: body (required), templateId (required), collectiveId (required), mode.

upload_attachmentA
DestructiveIdempotent

Upload an attachment to a page. Creates the attachment directory if needed. Returns a percent-encoded relativePath ready to paste into markdown (e.g. ![alt](.attachments.{pageId}/filename.png)).

Inputs: pageId (required), content (required), filename (required), collectiveId (required), +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 57 tools

    Disambiguation4/5

    Most tools use a clear resource+action pattern, so pages, tags, templates, attachments, and shares are easy to tell apart. A few near-neighbors require careful reading, such as search vs search_in_collective, update_collective vs set_page_mode, and update_template vs update_template_content, but their descriptions disambiguate them effectively.

    Naming Consistency4/5

    The snake_case verb_noun convention is strong and consistently used across collectives, pages, tags, templates, attachments, and shares. Minor deviations like search and ping as bare verbs, plus the inconsistent permanent-delete terms (permanently_delete_collective vs purge_page), keep it from a perfect 5.

    Tool Count1/5

    With 57 tools, this is far beyond a typical agent-facing MCP surface and creates significant selection overhead. Even though the domain is broad, the count sits in the extreme-mismatch range and would benefit from consolidation or splitting into smaller focused servers.

    Completeness4/5

    The surface covers nearly all lifecycle operations for collectives, pages, tags, templates, attachments, and shares, including trash, versions, and search. Minor gaps exist, such as no way to list favorited pages or list/purge trashed attachments, but agents can generally work around them.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A self-hosted MCP server that exposes Nextcloud files, calendar, notes, and search as tools for Claude.ai, authenticating via Nextcloud OAuth.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables Claude to list, read, write, create, delete, and search files on a self-hosted Nextcloud instance via WebDAV, with additional Obsidian vault-aware operations for frontmatter, tags, backlinks, and wikilinks.
      MIT

    Appeared in Searches