\n\n# Remnus\n\n**Open-source MCP-native workspace for humans and AI agents.**\n\nKanban boards, databases, and pages that Claude, Cursor, and any AI agent can read and write via MCP — alongside you.\n\n[](https://github.com/Ranork/remnus-app/stargazers)\n[](LICENSE)\n[](https://vercel.com/new/clone?repository-url=https://github.com/Ranork/remnus-app)\n[](https://smithery.ai/servers/ranorkk/remnus)\n[](https://registry.modelcontextprotocol.io)\n\n---\n\n## What is Remnus?\n\nRemnus is the Human-Agent Collaborative Workspace, built around the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Every page, database, and kanban board in your workspace is accessible to AI agents via a first-class MCP server — connect editors with one-click **OAuth 2.1 (PKCE)**, or use a scoped **bearer token** for headless / CI agents.\n\n**Unlike Notion's MCP integration**, Remnus is designed for headless, CI/CD, and coding agent workflows from day one.\n\n## OKF-native context, not a workspace dump\n\nRemnus uses Open Knowledge Format (OKF) ideas as a portable knowledge contract. Pages can carry descriptions, types, tags, sources, lifecycle state, freshness dates, and revision-bound review signals. OKF v0.2 import/export is the interchange layer; the editable Remnus workspace remains canonical.\n\nThe `prepare_context` MCP tool turns a concrete task into Context Pack v2: a token-budgeted set of concepts ranked by BM25 relevance, native metadata, page links, freshness, and trust. **Smart** mode advertises this context-first flow automatically for meaningful work. **Strict** mode additionally requires the same agent's short-lived `contextRunId` before Remnus MCP mutations.\n\nThis does not let an MCP server control local files, shell commands, or Git. Repository-level enforcement uses the supplied [`AGENTS.md` and `CLAUDE.md` snippets](integrations/context-first/README.md). Read the public [Context-First MCP guide](https://www.remnus.com/wiki/context-first) and the implementation story, [How Remnus Uses OKF to Give AI Agents Better Context](https://www.remnus.com/docs/okf-context-engine-for-ai-agents).\n\n## Features\n\n- **Pages** — Markdown editor with slash commands, nested sub-pages, and icons\n- **Databases** — Customizable columns, Table / Kanban / Calendar views, filters, sorts\n- **MCP Server** — 24 tools + 6 resources + 7 prompts over stateless Streamable HTTP\n- **OKF-native context** — Portable knowledge metadata, exact-revision reviews, Context Pack v2, and Smart/Strict MCP policies\n- **Agent auth** — One-click OAuth 2.1 + PKCE (RFC 7591 dynamic registration) for editors, or scoped read/write personal access tokens for headless agents\n- **Multi-workspace** — Invite members, role-based access (owner / member / viewer)\n- **Desktop app** — Tauri v2 shell for Windows, macOS, Linux\n- **Mobile** — Capacitor v8 for iOS and Android (loads remnus.com)\n- **i18n** — English, Türkçe, हिन्दी, Español, Français, Deutsch, 中文, Русский\n\n## Quick Start — Self-host\n\n### Local Development\n\n```bash\ngit clone https://github.com/Ranork/remnus-app.git\ncd remnus-app\ncp .env.example .env # fill in AUTH_SECRET + OAuth credentials\nnpm install\nnpm run db:migrate\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000). The first user to sign up is auto-promoted to admin.\n\n### Docker Compose (5-minute setup)\n\nIf you prefer to run Remnus using Docker:\n\n1. Clone the repository and navigate into it:\n ```bash\n git clone https://github.com/Ranork/remnus-app.git\n cd remnus-app\n ```\n2. Copy the environment template and fill in the required variables (especially `AUTH_SECRET` and OAuth credentials):\n ```bash\n cp .env.example .env\n ```\n3. Start the application:\n ```bash\n docker compose up -d\n ```\n4. Access Remnus at `http://localhost:3000`. The SQLite database will be persisted automatically using a Docker volume.\n\n### Deploy\n\n[](https://vercel.com/new/clone?repository-url=https://github.com/Ranork/remnus-app)\n[](https://railway.app/new/template?template=https://github.com/Ranork/remnus-app)\n\n### Add MCP to your editor\n\nAfter signing in, open the **AI Agents** panel from the sidebar and click **Connect editor**. It walks you through every supported editor (Cursor, VS Code, Claude Code, Codex, Windsurf, and more).\n\n[](https://docs.cursor.com/context/model-context-protocol)\n[](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)\n\n#### Install from a registry\n\nRemnus is published on the [official MCP Registry](https://registry.modelcontextprotocol.io) (`io.github.Ranork/remnus`) and on [Smithery](https://smithery.ai/servers/ranorkk/remnus), so MCP-aware clients and directories can discover it automatically. Smithery offers one-click install across many clients (Claude, Cursor, VS Code, Codex, Windsurf, and more) — open the [Smithery page](https://smithery.ai/servers/ranorkk/remnus) and click **Add to toolbox**, or use the Smithery CLI to install straight into a client's config:\n\n```bash\nnpx -y smithery@latest mcp add ranorkk/remnus --client claude\n```\n\nSwap `--client` for `cursor`, `vscode`, `codex`, `windsurf`, etc. Either way, the first connection runs the same OAuth 2.1 sign-in — no token to paste.\n\n**Recommended — OAuth (token-less):** point your editor at the MCP URL and approve the consent screen on first connect. Your editor runs the OAuth 2.1 flow automatically — nothing to copy.\n\n```json\n{\n \"mcpServers\": {\n \"remnus\": {\n \"type\": \"http\",\n \"url\": \"https://your-instance.com/api/mcp\"\n }\n }\n}\n```\n\n**Headless / CI — personal access token:** create a scoped token from the AI Agents panel and send it as a bearer header.\n\n```json\n{\n \"mcpServers\": {\n \"remnus\": {\n \"type\": \"http\",\n \"url\": \"https://your-instance.com/api/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer \"\n }\n }\n }\n}\n```\n\n## MCP Tools\n\n| Tool | Scope | Description |\n|------|-------|-------------|\n| `prepare_context` | read | Build Context Pack v2 (BM25 + OKF metadata + graph) and return a short-lived `contextRunId` |\n| `search_workspace` | read | Full-text search across pages and databases |\n| `list_workspace` | read | List sidebar items with pagination |\n| `get_page` | read | Get a page or database row by ID |\n| `get_pages` | read | Get multiple pages/rows by ID in one call (batch `get_page`) |\n| `get_database_schema` | read | Get column schema of a database |\n| `query_database` | read | Query rows with filters and pagination |\n| `list_members` | read | List workspace members with roles |\n| `query_audit_log` | read | Filtered agent activity log |\n| `get_changes_since` | read | Compact, chronological feed of what changed since a timestamp or cursor |\n| `get_related_pages` | read | A page's parent, children, outgoing links, backlinks, and database siblings |\n| `create_page` | write | Create a standalone page or database row |\n| `update_page` | write | Update title, content, or properties |\n| `bulk_update_pages` | write | Update multiple rows in one call |\n| `delete_page` | write | Delete a page (requires `confirm: true`) |\n| `bulk_delete_pages` | write | Delete up to 100 pages/rows/databases in one call (requires `confirm: true`) |\n| `move_item` | write | Move item to a new parent |\n| `bulk_move_items` | write | Move up to 100 items in one call, reparenting or moving rows to a different database |\n| `create_database` | write | Create a database with custom schema |\n| `update_database_schema` | write | Add or remove columns |\n| `create_database_view` | write | Add a table/kanban/calendar view |\n| `update_database_view` | write | Rename a view or patch its config |\n| `delete_database_view` | write | Delete a saved view (requires `confirm: true`) |\n| `add_comment` | write | Add a comment to a page or row (agent comments are append-only) |\n\n## Tech Stack\n\n- **Framework:** Next.js 16.2.6 (App Router)\n- **Database:** SQLite via Drizzle ORM + `@libsql/client` (Turso-compatible)\n- **Auth:** Auth.js v5 — Google & GitHub OAuth\n- **Styling:** Tailwind CSS + Lucide icons\n- **Desktop:** Tauri v2 (Rust)\n- **Mobile:** Capacitor v8\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). All contributions are welcome — bug fixes, new MCP tools, translations, and docs.\n\n## License\n\n[AGPL-3.0](LICENSE) — free to self-host and modify. SaaS forks must open-source their changes.\n",
"bytes": 9156,
"sha": "08d865c192c3a57fa2f27acaa2ac101b977fc373add18f71267f43820d14f880",
"repo_slug": "ranork/remnus-app",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_ranork_remnus_a7751b62/readme"
}
![\"Remnus\"](\"public/remnus-animation.gif\")
\n