nanace MCP server
Commit Oct 28, 2026Lets an AI client access a self-hosted team knowledge base with semantic search, a knowledge graph, and markdown support.
Also known as felichita/nanace
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 28, 2026
- License
- Apache-2.0
What is nanace MCP?
nanace lets an AI client access a self-hosted team knowledge base with semantic search, a knowledge graph, and markdown support.
Summary generated from the project's README
About nanace MCP server
Connecting Claude to a self-hosted team knowledge base is what nanace enables through its MCP server. This tool allows AI clients to interact with a multi-tenant markdown wiki that features semantic search, a knowledge graph, and role-based access control. It is designed for teams that need to maintain a shared source of truth that an AI can both read from and write to.
Users can set up the system using a local Docker Compose stack with PostgreSQL and Qdrant, or deploy a standalone server. To connect Claude Desktop or Claude Code, you provide a personal access token and the API URL. The server supports Google OAuth for authentication, while developers can use a development login mode for testing. When configured with write permissions, Claude can use tools like create_context and update_context to manage pages directly.
What you can do with it
- 1Automated work loggingA developer can use a specialized skill to record session progress directly onto a specific task page.
- 2Semantic knowledge retrievalAn AI client can search through team documentation using meaning-based queries rather than just keywords.
- 3Wiki schema managementThe system can automatically follow team-defined templates and tags to keep documentation organized.
- 4Claude memory migrationTeams can convert existing Claude Code memory files into a structured, linked knowledge base.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
NANACE_API_URLNANACE_BASE_URLNANACE_TOKEN
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 reachablefelichita/nanace is public and reachablegithub.com/felichita/nanace ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-28github.com/felichita/nanace ↗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 model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubnanace
Multi-tenant markdown knowledge base with team-level RBAC and semantic search, exposed to Claude through MCP. See ARCHITECTURE.md.
Quick start
cp .env.example .env # set NANACE_JWT_SECRET (openssl rand -base64 48)
make run # starts PostgreSQL + Qdrant, then the API on :8080
The first start downloads the bge-small-en-v1.5 model (~130 MB) into
.fastembed_cache/.
Google sign-in
- In Google Cloud Console create an OAuth client of type Web application
with redirect URI
http://127.0.0.1:8080/api/v1/auth/google/callback(use yourNANACE_PUBLIC_URL). - Set
NANACE_GOOGLE_CLIENT_ID,NANACE_GOOGLE_CLIENT_SECRET, and optionallyNANACE_GOOGLE_ALLOWED_DOMAINSin.env. - Open http://127.0.0.1:8080/auth/complete, sign in, and create a
personal access token (
readscope is enough for Claude).
Without Google, NANACE_DEV_LOGIN=true gives a session for any email:
curl -s -X POST localhost:8080/api/v1/auth/dev-login \
-H 'Content-Type: application/json' -d '{"email":"you@example.com"}'
Connect Claude (MCP)
In the desktop app, choose Connect to Claude in the sidebar. It registers the bundled MCP server with Claude Code (all projects) and/or Claude Desktop, each with its own read-only token. Check Allow Claude to create and edit pages to let Claude save notes ("save this to nanace"). To set it up by hand instead, build the MCP server once:
cargo build --release -p nanace-mcp
Claude Code, with a personal access token:
claude mcp add nanace \
--env NANACE_API_URL=http://127.0.0.1:8080 \
--env NANACE_TOKEN=nnc_pat_... \
-- "$PWD/target/release/nanace-mcp"
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"nanace": {
"command": "/absolute/path/to/target/release/nanace-mcp",
"env": {
"NANACE_API_URL": "http://127.0.0.1:8080",
"NANACE_TOKEN": "nnc_pat_..."
}
}
}
}
Instead of NANACE_TOKEN you can set NANACE_TOKEN_FILE to a file that
holds the token (re-read on every request; keep it readable only by you), so
the token stays out of config files.
Against a development API you can use NANACE_DEV_EMAIL=you@example.com
instead of a token. NANACE_ORG_ID picks a default organization.
NANACE_ALLOW_WRITES=true (with a write-scoped token) adds the
create_context and update_context tools.
Work-log skill for Claude Code
integrations/claude-code/skills/nanace is a Claude Code skill: /nanace PROJECT-2345 records what was done in the current session on the task's page
(appending a dated section, or creating the page). It treats each team as a
wiki: before writing it reads the team's Wiki: Schema page (page types, title
prefixes, templates, tags), and afterwards it updates the related Topic: page
and Wiki: Index. A team without a schema is initialized from
schema-template.md, and the new schema is marked as the default for review.
It needs the write tools (Allow Claude to create and edit pages).
Install or update the MCP server binary and the skill, and connect Claude Code
to your server, with one command (run it again later to update). Point it at
your server with NANACE_API_URL; the default is http://127.0.0.1:8080:
macOS / Linux:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/felichita/nanace/HEAD/integrations/claude-code/install.sh)"
# with your server:
NANACE_API_URL=https://nanace.example.com \
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/felichita/nanace/HEAD/integrations/claude-code/install.sh)"
Windows (PowerShell):
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/felichita/nanace/HEAD/integrations/claude-code/install.ps1 | iex"
# with your server, in a PowerShell window:
$env:NANACE_API_URL = 'https://nanace.example.com'
irm https://raw.githubusercontent.com/felichita/nanace/HEAD/integrations/claude-code/install.ps1 | iex
What the installer does:
nanace-mcp: downloads it from the latest GitHub release (NANACE_VERSION=v0.1.3pins one), checks the.sha256, and installs it to~/.local/bin(Windows:%LOCALAPPDATA%\nanace\bin; override withNANACE_BIN_DIR). A.nanace-mcp.versionfile next to it records the release and checksum, so a re-run downloads nothing when the binary is current, updates it when a newer release exists, and repairs it when the file was changed. The replacement is atomic, so a running server is not affected. Published builds: macOS arm64, Linux x64/arm64 (glibc), Windows x64; on other platforms (for example Intel macOS) the binary is skipped — use the desktop app, which bundles it, orcargo build --release -p nanace-mcp.NANACE_SKIP_BINARY=1installs only the skill.- Skill: copies it to
~/.claude/skills/nanace(or$CLAUDE_CONFIG_DIR/skills/nanace) fromNANACE_REF(defaultmain). An older version is moved to~/.claude/skill-backups/first. - Claude Code connection (interactive, asks before changing anything):
connects Claude Code to the server at
NANACE_API_URL(defaulthttp://127.0.0.1:8080, for exampleNANACE_API_URL=https://nanace.example.com). It opens<server>/auth/complete, where you sign in and create a token with scopewrite, reads the token with hidden input, checks it against the API, and saves it to~/.config/nanace/claude-code.token(Windows:%LOCALAPPDATA%\nanace\claude-code.token; override withNANACE_TOKEN_FILE), readable only by you. If you belong to several organizations it asks which one to use (or setNANACE_ORG_ID). Then it runsclaude mcp add nanace --scope userwithNANACE_TOKEN_FILE, so the token is never in a config file or a command line. A re-run reuses the saved token, and does nothing when Claude Code already uses thisnanace-mcp(NANACE_RECONNECT=1connects again, e.g. after changing the server). If Claude Code runs another copy (such as the desktop app's, which Connect to Claude registers and the app updates), it asks before switching. Without a terminal, or withNANACE_CONNECT=0, it only prints the manual steps. New users need an account on the server and, to save pages, a team role ofwriterfrom an admin; the installer warns when that is missing.
To install the skill from a local clone instead of GitHub:
NANACE_BASE_URL="file://$PWD/integrations/claude-code/skills/nanace" integrations/claude-code/install.sh
Desktop app
Requires Node 20+ and the Rust toolchain. With the API running:
make desktop-dev # npm install + tauri dev
make desktop-build # release bundle in apps/desktop/src-tauri/target/release/bundle
Sign in with Google (opens your browser) or, against a dev server, with any
email. Import Claude memory, in the sidebar or ⌘K, turns Claude Code's
memory files (~/.claude/projects/*/memory) into linked pages. The app stores a personal access token named "nanace desktop" in the
macOS Keychain (or the OS keyring).
Docker
The Docker workflow publishes the backend image for linux/amd64 and
linux/arm64 for every v* tag (pull requests only build it):
docker pull ghcr.io/felichita/nanace-server:latest # or :0.1.2, :0.1
The image runs nanace-server as a non-root user on port 8080 and has the
embedding model baked in, so it starts without internet access. It does not
contain nanace-mcp: Claude runs that on each user's machine (it ships with
the desktop app and the release archives) and points it at the server. Configure it with the same environment variables as
.env.example (DATABASE_URL, QDRANT_URL, NANACE_JWT_SECRET,
NANACE_PUBLIC_URL, ...); PostgreSQL must give it a non-superuser role (see
deploy/postgres/init.sql). Probes: GET /livez (liveness: the process
answers, no dependencies touched) and GET /readyz (readiness: PostgreSQL and
Qdrant answer; /healthz is the same).
Build it locally with docker build -t nanace-server ., or run the whole
stack (API server, PostgreSQL, Qdrant) with Docker Compose:
make up # docker compose --profile app up -d --build; settings from .env
make logs # follow the server logs
make down # stop it (data volumes are kept)
The server listens on 127.0.0.1:8080; set NANACE_HOST_BIND=0.0.0.0 to
share it on your network.
Logs and metrics
- Logs:
NANACE_LOG_FORMAT=jsonwrites one JSON object per line, for Loki or ELK (the default istext). Request logs carry the path only, never query strings. - Metrics:
NANACE_METRICS_BIND=0.0.0.0:9090serves Prometheus metrics on/metricson that separate listener, so the public ingress never exposes them. Docker Compose serves them on127.0.0.1:9090.nanace_http_requests_totalandnanace_http_request_duration_seconds, by method, route pattern and status;nanace_embedding_duration_seconds, bypassageorquery.
Upgrades
By default the server upgrades the database when it starts:
- it applies the SQL migrations;
- it runs the application upgrades written in Rust (for example backfilling derived data);
- if
NANACE_EMBEDDERnow selects a different model, it reindexes.
On Kubernetes, run that as a separate step instead (an init container, a
Job, or a Helm pre-upgrade hook) and start the pods with
NANACE_RUN_MIGRATIONS=false. They then refuse to start on a database that
is behind or ahead of them:
nanace-server migrate --check # report only; exit status 1 when something is pending
nanace-server migrate # apply, then exit
To rebuild the vectors from PostgreSQL, for example after moving to a new or
empty Qdrant or changing the embedding model, run the reindex command. It
recreates each organization's collection; search for that organization is
incomplete until it finishes:
docker compose --profile app run --rm server reindex # all organizations
docker compose --profile app run --rm server reindex --org <id> # one organization
cargo run -p nanace-server -- reindex # from source, with .env
``` Unverified email login stays off in Compose unless
`NANACE_COMPOSE_DEV_LOGIN=true`.
## Releases
Prebuilt downloads are on the GitHub Releases page:
- **Desktop app:** macOS (Apple silicon and Intel), Windows x64, and Linux
x64/arm64 (AppImage, deb, rpm).
- **Server and MCP archives:** Linux x64/arm64, macOS arm64, Windows x64.
To publish a release, push a version tag:
```bash
git tag v0.1.0 && git push origin v0.1.0
The Release workflow builds everything on native runners, uploads it to a
draft release, and publishes it when every build succeeds. Builds are not
code-signed yet.
Development
make check # fmt, clippy -D warnings, unit tests
make test-integration # API, RLS and MCP tests (nanace_test DB + qdrant-test)
make test-model # real embedding model test
make desktop-check # desktop: tsc, vitest, clippy, Rust tests
License
Licensed under the Apache License, Version 2.0. Copyright 2026 Fedor Nikolaev.
nanace MCP questions
How do I connect Claude to nanace?
You can connect via the desktop app by choosing 'Connect to Claude' in the sidebar, or manually by building the MCP server and adding it to Claude Desktop or Claude Code using a personal access token.
Can Claude edit my knowledge base?
Yes, if you check the 'Allow Claude to create and edit pages' option or provide a write-scoped token with the NANACE_ALLOW_WRITES environment variable set to true.
Does the Docker image require internet access for embeddings?
No, the Docker image has the embedding model baked in, allowing it to start without internet access.
How can I use nanace for work logging in Claude Code?
You can use the nanace skill with the /nanace command to record session progress on specific task pages, which automatically updates related topic pages and indices.