Your Nextcloud instance is more than just a bucket for files—it is a galaxy of ideas, projects, and knowledge. But until now, you've been navigating it in the dark, relying on exact filenames and rigid keywords.
It's time to turn the lights on.
Astrolabe is a fully integrated Nextcloud application that transforms your server into a semantic intelligence engine. It doesn't just store your data; it maps it, understands it, and connects it to the AI future.
Forget clunky external tools. Astrolabe registers as a native Nextcloud Search Provider.
- Seamless: Lives right in the standard Nextcloud search bar you already use
- Semantic: Type "marketing strategy for the winter launch" and Astrolabe finds the relevant PDFs, chat logs, and text files—even if those exact words never appear in the document
- Intelligent: It finds the concept, not just the string
Data shouldn't just be a list; it should be a landscape. Astrolabe includes a dedicated dashboard that visualizes your document chunks as a 3D PCA Vector Plot.
- See the Connections: View your data as a constellation of points in 3D space
- Explore Clusters: Visually identify how your documents relate to one another
- True "Astroglobe" Experience: Rotate, zoom, and fly through your semantic universe just like navigators once studied the stars
Astrolabe isn't just for humans; it's for your AI agents, too. It acts as a bridge, running a Model Context Protocol (MCP) Server directly from your Nextcloud.
- Bring Your Own Brain: Connect external AI clients (like Claude Desktop or Cursor) to your private data
- Agentic Workflows: Enable LLMs to "sample" your files, read content, and perform complex reasoning tasks using your Nextcloud data as the source of truth
- Private & Secure: Your data never leaves your infrastructure
- Open Apps in your Nextcloud
- Search for "Astrolabe"
- Click "Download and enable"
# Clone into your Nextcloud apps directory
cd /path/to/nextcloud/apps
git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
cd nextcloud-mcp-server/third_party/astrolabe
# Install dependencies
composer install
# Enable the app
php /path/to/nextcloud/occ app:enable astrolabeAdd this to your Nextcloud config/config.php:
'mcp_server_url' => 'http://localhost:8000',The MCP server handles semantic search and AI agent connections. See the MCP Server Installation Guide for details.
Quick start with Docker:
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth- Go to Settings → Personal → Astrolabe
- Click "Authorize Access"
- Sign in to your identity provider
- Approve the requested permissions
That's it! You can now use semantic search and explore your data universe.
Located in: Settings → Personal → Astrolabe
- Semantic Search Dashboard: Interactive 3D visualization of your document chunks
- OAuth Authorization: Authorize Nextcloud to access the MCP server on your behalf
- Session Information: View connection status and authentication details
- Connection Management: Revoke access or disconnect when needed
Located in: Settings → Administration → Astrolabe
- Server Status: Monitor MCP server health and version
- Vector Sync Metrics: See how many documents are indexed, processing rates, and sync status
- Configuration Validation: Verify server URL and connectivity
- Feature Availability: Check which capabilities are enabled
- Vector Space Visualization: Toggle the interactive 3D vector plot on the app page. Enabled by default; when disabled, the plot is hidden for all users and its PCA computation is skipped on each search.
Astrolabe integrates directly with Nextcloud's Unified Search:
- Available in the top search bar across all Nextcloud pages
- Returns semantic matches ranked by relevance
- Shows excerpts from matching documents
- Links directly to source files in Nextcloud
- Research: Find all notes related to a project, even if they use different terminology
- Organization: Discover forgotten documents related to your current work
- Exploration: Visualize how your knowledge connects and evolves over time
- Knowledge Discovery: Surface institutional knowledge that would otherwise stay buried
- Collaboration: Find team members working on similar problems
- Documentation: Locate relevant documentation without knowing exact titles
- AI Integration: Connect Claude Desktop, Cursor, or other MCP clients to Nextcloud
- RAG Workflows: Build retrieval-augmented generation pipelines on your private data
- Custom Agents: Use the MCP protocol to create specialized workflows
- Nextcloud: Version 30 or later
- MCP Server: Running instance (Docker recommended)
- Identity Provider: OAuth provider supporting PKCE (Nextcloud OIDC Login or Keycloak)
- Vector Sync: Optional but recommended for semantic search (see configuration guide)
Cannot connect to MCP server:
- Verify
mcp_server_urlinconfig.php - Check MCP server is running:
curl http://localhost:8000/health - Review logs:
tail -f data/nextcloud.log
Authorization fails:
- Ensure MCP server is in OAuth mode
- Verify identity provider is accessible
- Check browser console for errors
Semantic search returns no results:
- Verify vector sync is enabled and running
- Check indexing status in Admin settings
- Allow time for initial indexing to complete
For more help, see the Troubleshooting Guide.
We welcome contributions! Here's how to get started:
- Fork the nextcloud-mcp-server repository
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes in
third_party/astrolabe/ - Test thoroughly with a local Nextcloud instance
- Submit a pull request
See CONTRIBUTING.md for detailed guidelines.
AGPL-3.0
Astrolabe is developed as part of the Nextcloud MCP Server project, bringing the power of semantic search and AI integration to Nextcloud.
Author: Chris Coutinho chris@coutinho.io
Your Data. Mapped. Visualized. Connected.
Install Astrolabe for Nextcloud.