Remnus
Open-source MCP-native workspace for humans and AI agents.
Kanban boards, databases, and pages that Claude, Cursor, and any AI agent can read and write via MCP — alongside you.
What is Remnus?
Remnus is a Notion-like workspace built around the Model Context Protocol (MCP). 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.
Unlike Notion's MCP integration, Remnus is designed for headless, CI/CD, and coding agent workflows from day one.
Features
- Pages — Markdown editor with slash commands, nested sub-pages, and icons
- Databases — Customizable columns, Table / Kanban / Calendar views, filters, sorts
- MCP Server — 14 tools + 4 resources + 5 prompts, Streamable HTTP + SSE dual transport
- Agent auth — One-click OAuth 2.1 + PKCE (RFC 7591 dynamic registration) for editors, or scoped read/write personal access tokens for headless agents
- Multi-workspace — Invite members, role-based access (owner / member / viewer)
- Desktop app — Tauri v2 shell for Windows, macOS, Linux
- Mobile — Capacitor v8 for iOS and Android (loads remnus.com)
- i18n — English, Türkçe, Español, Français, Deutsch, हिन्दी
Quick Start — Self-host
Local Development
git clone https://github.com/Ranork/remnus-app.git
cd remnus-app
cp .env.example .env # fill in AUTH_SECRET + OAuth credentials
npm install
npm run db:migrate
npm run dev
Open http://localhost:3000. The first user to sign up is auto-promoted to admin.
Docker Compose (5-minute setup)
If you prefer to run Remnus using Docker:
- Clone the repository and navigate into it:
git clone https://github.com/Ranork/remnus-app.git cd remnus-app - Copy the environment template and fill in the required variables (especially
AUTH_SECRETand OAuth credentials):cp .env.example .env - Start the application:
docker compose up -d - Access Remnus at
http://localhost:3000. The SQLite database will be persisted automatically using a Docker volume.
Deploy
Add MCP to your editor
After 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).
Install from a registry
Remnus is published on the official MCP Registry (io.github.Ranork/remnus) and on Smithery, 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 and click Add to toolbox, or use the Smithery CLI to install straight into a client's config:
npx -y smithery@latest mcp add ranorkk/remnus --client claude
Swap --client for cursor, vscode, codex, windsurf, etc. Either way, the first connection runs the same OAuth 2.1 sign-in — no token to paste.
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.
{
"mcpServers": {
"remnus": {
"type": "http",
"url": "https://your-instance.com/api/mcp"
}
}
}
Headless / CI — personal access token: create a scoped token from the AI Agents panel and send it as a bearer header.
{
"mcpServers": {
"remnus": {
"type": "http",
"url": "https://your-instance.com/api/mcp",
"headers": {
"Authorization": "Bearer <your-token>"
}
}
}
}
MCP Tools
| Tool | Scope | Description |
|---|---|---|
search_workspace | read | Full-text search across pages and databases |
list_workspace | read | List sidebar items with pagination |
get_page | read | Get a page or database row by ID |
get_database_schema | read | Get column schema of a database |
query_database | read | Query rows with filters and pagination |
list_members | read | List workspace members with roles |
query_audit_log | read | Filtered agent activity log |
create_page | write | Create a standalone page or database row |
update_page | write | Update title, content, or properties |
bulk_update_pages | write | Update multiple rows in one call |
delete_page | write | Delete a page (requires confirm: true) |
move_item | write | Move item to a new parent |
create_database | write | Create a database with custom schema |
update_database_schema | write | Add or remove columns |
Tech Stack
- Framework: Next.js 15 (App Router)
- Database: SQLite via Drizzle ORM +
@libsql/client(Turso-compatible) - Auth: Auth.js v5 — Google & GitHub OAuth
- Styling: Tailwind CSS + Lucide icons
- Desktop: Tauri v2 (Rust)
- Mobile: Capacitor v8
Contributing
See CONTRIBUTING.md. All contributions are welcome — bug fixes, new MCP tools, translations, and docs.
License
AGPL-3.0 — free to self-host and modify. SaaS forks must open-source their changes.