Slipbox MCP Server
Slipbox MCP Server gives an AI assistant a full Zettelkasten knowledge-management toolkit: create and organize atomic notes, link them semantically, search and explore the graph, and maintain structure through automatic cluster detection.
Note management: Create, read, update, and delete notes as markdown files with YAML frontmatter, supporting five types (fleeting, literature, permanent, structure, hub).
Semantic linking: Create and remove typed directional links (reference, extends, refines, contradicts, questions, supports, related), optionally bidirectional with inverse links.
Graph exploration: View linked notes, find central/hub-worthy notes, find orphaned/unintegrated notes, and discover similar notes via shared tags, links, and content overlap.
Search & discovery: Full-text BM25 search by query, tags, or note type; list notes by date range; list all tags for consistent tagging.
Cluster analysis & maintenance: Get pending cluster reports, create structure notes from detected clusters, refresh cluster analysis, and dismiss clusters you don't need.
Indexing & portability: Rebuild the SQLite index from plain markdown files after external edits, ensuring zero lock-in and file-based source of truth.
Workflow support: Ship with Zettelkasten prompts/skills for knowledge creation, exploration, synthesis, note analysis, and cluster maintenance to guide the agent's workflow.
Allows notes to be managed as plain markdown files viewable in Obsidian, and provides a companion plugin for visualizing typed links in a color-coded semantic graph within Obsidian.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Slipbox MCP Server search for notes on complex adaptive systems"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Slipbox MCP Server

Give your AI assistant an active role in managing your knowledge. Slipbox is an MCP server that turns any MCP-compatible agent into a Zettelkasten partner -- creating atomic notes, forming semantic links, detecting emergent clusters, and synthesizing insights from your existing knowledge.
Your ideas in, structured knowledge out. The agent handles the formatting, linking, and integration.
New to the method? Start with Introduction to the Zettelkasten Method for the why behind atomic notes and linked thinking. To see how Slipbox primes your agent with that method, read the server instructions it ships automatically on connect.
Built and tested with Claude. Works with any MCP client (Claude Desktop, Claude Code, OpenCode, Copilot, or anything that speaks MCP).
Plain files, zero lock-in. Notes are markdown with YAML frontmatter -- readable in Obsidian, Foam, Logseq, or any editor. The SQLite database is an index, not the source of truth. Delete it and rebuild from files anytime.
19 MCP tools for notes, links, search, graph analysis, and cluster management
6 workflow prompts (plus matching skills) encoding the Zettelkasten method so you don't re-learn it every session
BM25 full-text search across titles and content via SQLite FTS5
Cluster detection finds emergent topic groups and scaffolds structure notes
Seven typed links (reference, extends, refines, contradicts, questions, supports, related)
Python 3.10+ | macOS or Linux

Walkthrough
![]()
Related MCP server: vault-master-mcp
Quick Start
1. Install
pipx install slipbox-mcp
# or, with uv:
uv tool install slipbox-mcpThis puts a slipbox-mcp launcher on your PATH (in ~/.local/bin). That single command is the whole MCP server: no clone, no PYTHONPATH, no hardcoded venv Python path. Everything below uses it. To try it without installing at all, uvx slipbox-mcp runs the server in a throwaway environment.
(Working on Slipbox itself? See Development for the clone + editable-install setup.)
2. Pick a Data Directory
One variable, SLIPBOX_BASE_DIR, configures everything: notes land in <base>/data/notes and the SQLite index in <base>/data/db/zettelkasten.db. The server creates these on first run with owner-only (0700) permissions.
Point SLIPBOX_BASE_DIR (or the individual SLIPBOX_NOTES_DIR / SLIPBOX_DATABASE_PATH paths below) at a dedicated data directory you control, not a shared or system location. These paths are used as-is: the server manages the notes tree and index under them, and it treats the notes directory as the source of truth when it rebuilds the index.
# Example: use any absolute path you like
/Users/yourname/.local/share/mcp/slipboxUse a full absolute path. A leading
~is not expanded inside MCP client config files and would create a literal~directory.
3. Connect to Your MCP Client
Claude Code (one command, no file editing):
claude mcp add slipbox \
--env SLIPBOX_BASE_DIR=/Users/yourname/.local/share/mcp/slipbox \
-- slipbox-mcpClaude Desktop (edit the config file):
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:
~/.config/claude/claude_desktop_config.json
{
"mcpServers": {
"slipbox": {
"command": "slipbox-mcp",
"env": {
"SLIPBOX_BASE_DIR": "/Users/yourname/.local/share/mcp/slipbox"
}
}
}
}Desktop PATH caveat: the macOS Desktop app doesn't always inherit
~/.local/binon its PATH, so the bare"slipbox-mcp"may not resolve. If the server fails to start, replace"command": "slipbox-mcp"with the absolute path printed bywhich slipbox-mcp(typically/Users/yourname/.local/bin/slipbox-mcp).
Other MCP clients: register slipbox-mcp as the server command with SLIPBOX_BASE_DIR in its environment. The command and env are the same everywhere.
Instead of SLIPBOX_BASE_DIR, set absolute paths individually. Optional SLIPBOX_LOG_LEVEL is one of DEBUG, INFO, WARNING, ERROR.
"env": {
"SLIPBOX_NOTES_DIR": "/Users/yourname/.local/share/mcp/slipbox/notes",
"SLIPBOX_DATABASE_PATH": "/Users/yourname/.local/share/mcp/slipbox/data/db/zettelkasten.db",
"SLIPBOX_LOG_LEVEL": "INFO"
}The cluster report is written beside the database as cluster-analysis.json. Set SLIPBOX_CLUSTER_REPORT_PATH to an absolute path to put it elsewhere.
4. Restart and Verify
Restart your client (Claude Code reloads on next launch; quit and reopen Claude Desktop).
Ask your agent:
"Create a test note about something"
"Search my slipbox for test"
"Find orphaned notes"
In Action
The hero above is the core loop. Here's the rest of what the agent does.
Proactive Maintenance
The agent reads the slipbox://maintenance-status resource at session start and surfaces clusters that need organizing.

Full-Text Search
BM25-ranked search across notes via slipbox_search_notes.

Knowledge Graph: Central Notes
slipbox_find_central_notes surfaces the structural anchors of the graph -- the notes everything else orbits.

Note Analysis
The analyze_note prompt evaluates atomicity, finds real connections in the existing graph, suggests tags, and rewrites for clarity.

Source Decomposition
The knowledge_creation prompt splits an article into atomic literature notes with proper citation and links.

Cluster Detection
slipbox_get_cluster_report finds groups of co-occurring tags that lack a structure note. Scored by size, orphan ratio, link density, and recency.

Structure Note Creation
slipbox_create_structure_from_cluster scaffolds a structure note, links all member notes, and dismisses the cluster.

Orphaned Notes
slipbox_find_orphaned_notes surfaces unintegrated knowledge -- candidates for connection or deletion.

Similar Notes
slipbox_find_similar_notes computes similarity from shared tags, common links, and content overlap.

Graph Traversal
slipbox_get_linked_notes shows typed links from a hub note, grouped by link type.

Knowledge Synthesis
The knowledge_synthesis prompt finds bridges between unconnected areas and proposes synthesis notes from your existing knowledge.

Zero Lock-In: Plain Files in Obsidian
Notes are plain markdown. Open the vault in Obsidian and everything works -- rendered content, backlinks, and the knowledge graph.
For a graph that renders the typed links in color (supports, extends, refines, ...) rather than Obsidian's untyped built-in graph, install the companion plugin Slipbox Semantic Graph -- a force-directed view with human-readable titles and color-coded semantic link types. Install it manually from the 0.1.0 release: copy main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/slipbox-graph/, then enable it in Settings → Community plugins. (Once it's accepted into the official directory, you'll also be able to install it via Settings → Community plugins → Browse → search "Slipbox Semantic Graph".) It reads the same frontmatter id and ## Links section the server writes, so no extra configuration is needed. Open the view with the Open semantic graph command (Command Palette) or the git-fork ribbon icon.

The legend across the top maps each color to a link type (extends, refines, supports, contradicts, questions, related). Focus a structure note and its constellation comes into view. Here, Contract Testing Knowledge Map with its member notes orbiting it:

Optional: Automatic Cluster Detection
The background helpers below require a repository checkout and its own Python environment; pipx install and uv tool install install the server but do not put these scripts in your working directory. Set up the helpers once:
git clone https://github.com/jamesfishwick/slipbox-mcp.git
cd slipbox-mcp
uv sync
cp .env.example .envEdit the checkout's .env to use the same absolute data paths as your MCP client. For example, for a client whose SLIPBOX_BASE_DIR is /Users/yourname/.local/share/mcp/slipbox:
SLIPBOX_BASE_DIR=/Users/yourname/.local/share/mcp/slipbox
SLIPBOX_NOTES_DIR=/Users/yourname/.local/share/mcp/slipbox/data/notes
SLIPBOX_DATABASE_PATH=/Users/yourname/.local/share/mcp/slipbox/data/db/zettelkasten.db
SLIPBOX_LOG_LEVEL=INFORun the following commands from this checkout. Keep it in place while the background jobs are installed: their LaunchAgents use its absolute paths.
Cluster analysis scans all notes and computes similarity scores. Running it daily (6am) pre-computes results so slipbox_get_cluster_report() returns instantly. Without scheduling, cluster detection runs on-demand, which is slower for large collections.
Run manually after bulk imports, major reorganization, or when you want immediate results.
Install Cluster Detection (macOS)
chmod +x scripts/install-cluster-detection.sh
./scripts/install-cluster-detection.shThe installer detects your Python/venv path, generates the LaunchAgent plist, and loads it.
Manual Test (Cluster Detection)
source .venv/bin/activate
python scripts/detect_clusters.pyOutput saved to cluster-analysis.json next to the SQLite index (for example <base>/data/db/cluster-analysis.json), or to SLIPBOX_CLUSTER_REPORT_PATH when set.
Uninstall Cluster Detection
./scripts/install-cluster-detection.sh --uninstallOptional: macOS File Watcher for Auto-Indexing
The MCP server maintains a database index for fast searching. Editing notes in Obsidian (or any editor) makes the database stale until you run slipbox_rebuild_index.
The file watcher runs as a background daemon, monitoring your notes directory and automatically rebuilding the index when .md files change.
Use it if you frequently edit notes in Obsidian while also using Claude.
Install File Watcher (macOS)
Complete the helper setup above first, and create a note through your MCP client so the notes directory exists.
chmod +x scripts/install-file-watcher.sh
./scripts/install-file-watcher.shThe installer detects your Python/venv path, installs watchdog if needed, and loads the LaunchAgent. Starts on login and restarts if it crashes.
Manual Test
source .venv/bin/activate
python scripts/watch_notes.pyEdit a note file. You should see "rebuilding index..." in the watcher output.
Check Status
launchctl list | grep slipbox.watcher
# View logs
tail -f ~/.local/share/mcp/slipbox/watcher.logUninstall File Watcher
./scripts/install-file-watcher.sh --uninstallRecommended System Prompt
Slipbox ships a baseline automatically: every client receives the server instructions on connect, covering how to use the tools well -- note types, link semantics, quality standards, and core workflows like search-before-create. You don't add those yourself.
docs/SYSTEM_PROMPT.md is the opt-in layer on top: the autonomy and initiative directives a server shouldn't assert on its own. Add it to your agent's preferences or system prompt to enable:
Automatic knowledge capture during conversations
Cluster emergence detection at conversation start
Tools Reference
Core Note Operations
Tool | Description |
| Create atomic notes (fleeting/literature/permanent/structure/hub) |
| Retrieve note by ID or title |
| Update existing notes |
| Delete notes |
Linking
Tool | Description |
| Create semantic links between notes |
| Remove links |
| Delete a specific link (errors if link does not exist) |
| Get notes linked to/from a note |
Search & Discovery
Tool | Description |
| Search by text (BM25-ranked), tags, or type |
| Find notes similar to a given note |
| Find most connected notes |
| Find unconnected notes |
| List notes by date range |
| List all tags |
Cluster Analysis
Tool | Description |
| Get pending clusters needing structure notes |
| Create structure note from cluster |
| Regenerate cluster analysis |
| Permanently dismiss cluster from suggestions |
Maintenance
Tool | Description |
| Rebuild database index from files |
Prompts Reference
MCP prompts are reusable workflow templates that encode the Zettelkasten method so you don't re-explain it every session.
Prompt | Description | Use When |
| Process information into 3-5 atomic notes | Adding articles, ideas, or notes |
| Process larger volumes into 5-10 notes | Processing books or long-form content |
| Map connections to existing knowledge | Exploring how topics relate |
| Create higher-order insights | Finding bridges between ideas |
| Evaluate a note's fitness for the slipbox | Reviewing a new or existing note |
| Surface pending housekeeping | Start of a working session |
How to Invoke: Slash Commands and Skills
Each workflow ships two ways:
MCP prompts: served by the running server.
Skills: standalone bundles (
skills/<name>/) that run the same workflow and add natural-language triggering.
Five of the six skills are generated from the same PROMPT_* templates the server uses (src/slipbox_mcp/server/descriptions.py), and CI fails if the committed skills/ drift from those templates. The sixth, cluster-maintenance, is authored directly in scripts/build_skills.py because its MCP prompt is a runtime-rendered status message rather than a reusable workflow.
Slash commands are the reliable path. Claude Code surfaces MCP prompts as /mcp__<server>__<prompt>; type /mcp__slipbox-mcp__ for the picker:
/mcp__slipbox-mcp__knowledge_creation
/mcp__slipbox-mcp__knowledge_exploration
/mcp__slipbox-mcp__knowledge_synthesis
/mcp__slipbox-mcp__knowledge_creation_batch
/mcp__slipbox-mcp__analyze_note
/mcp__slipbox-mcp__cluster_maintenance(Installed skills also expose their own slash commands by directory name, e.g. /slipbox-analyze-note.)
Natural language works once the matching skill is installed. Just describe what you want:
Analyze this note for my slipbox: [paste note]
Add this to my slipbox: [paste article]
Synthesize my notes on attention and memory.Prose triggering depends on the skill being installed and your phrasing matching its description; fall back to the slash command if it doesn't fire. Asking the model to "use the analyze_note prompt" by name does not work. The model can't invoke an MCP prompt by name. Use a slash command, or let a skill trigger from natural language.
Installing Skills
Claude Code discovers skills from .claude/skills/ (per project) or ~/.claude/skills/ (global), not from a bare top-level skills/. Symlink or copy the ones you want into a discovery path (e.g. for this project):
mkdir -p .claude/skills
ln -s ../../skills/slipbox-analyze-note .claude/skills/slipbox-analyze-note
# ...or copy the directories, or symlink all sixClaude Desktop needs each skill as a .skill bundle. Build them, then upload:
python scripts/build_skills.py # writes dist/*.skillGo to Settings → Skills → Upload skill and select the bundles from dist/ you want. Each installs as both a slash command and a natural-language trigger.
After editing a prompt template in descriptions.py, re-run the build to regenerate the skills.
Link Types
Type | Use When | Inverse |
| Generic "see also" connection | reference |
| Building on another idea | extended_by |
| Clarifying or improving | refined_by |
| Opposing view | contradicted_by |
| Raising questions about | questioned_by |
| Providing evidence for | supported_by |
| Loose thematic connection | related |
Note Types
Type | Purpose |
| Quick captures, unprocessed thoughts |
| Ideas from sources with citation |
| Refined ideas in your own words |
| Maps organizing 7-15 related notes on a specific topic |
| Domain overview linking to structure notes; entry point for navigating a broad area of knowledge |
Structure vs. Hub: A structure note organizes a cluster of permanent notes around a single topic. It is a curated map one level above the notes themselves. A hub note operates one level higher still: it links to structure notes (and occasionally key permanent notes) across an entire knowledge domain. Where a structure note answers "what do I know about X?", a hub note answers "how is my knowledge of this whole domain organized?" Most Zettelkastens need only a handful of hub notes.
File Format
Notes are stored as Markdown files with YAML frontmatter:
---
id: "20251217T172432480464000"
title: "Poetry Revision Principles"
type: structure
tags:
- poetry
- revision
- craft
created: "2025-12-17T17:24:32"
updated: "2025-12-17T17:24:32"
---
# Poetry Revision Principles
Content here...
## Links
- reference [[20250728T125429845760000]] Member of structureYou can edit these files directly in any text editor or Obsidian. Run slipbox_rebuild_index after external edits.
Upgrading
After pulling new versions, restart Claude Desktop. If the release notes mention database changes, run slipbox_rebuild_index once to bring your existing database up to date.
Upgrading to FTS5 search (any version after the FTS5 release): The full-text search index is created automatically when the server starts against a new database. For existing databases, the FTS5 table will be created on first startup but will be empty until you run:
slipbox_rebuild_indexThis populates the BM25 index from your existing notes. Search results will not be relevance-ranked until this is done.
Troubleshooting
Server not loading in Claude Desktop
Confirm the launcher resolves:
which slipbox-mcpshould print a path (typically~/.local/bin/slipbox-mcp).If it resolves in your terminal but Desktop still can't start it, the GUI app isn't seeing
~/.local/binon its PATH. Replace"command": "slipbox-mcp"with the absolute path from step 1.Check Claude Desktop logs for errors.
slipbox-mcp: command not found
The console script wasn't installed or isn't on PATH. Reinstall with pipx install --editable . --force, then verify with which slipbox-mcp. If pipx's bin directory is missing from PATH, run pipx ensurepath and restart your shell.
Notes directory points to ~/... literally
If your notes directory ends up at ./~/... relative to CWD, you used ~ in the JSON config. Claude Desktop does not expand ~. Replace it with the full absolute path.
Search returns no results
The FTS5 index may not be populated. Run
slipbox_rebuild_indexonce to index existing notes.If you recently edited notes outside Claude, the index may be stale. Run
slipbox_rebuild_index.
slipbox_list_notes_by_date returns empty results
If start_date is later than end_date, no notes match and an empty result is returned. This is expected behavior, not an error.
Database out of sync
If notes were edited outside the MCP server:
slipbox_rebuild_indexCluster detection not running
launchctl list | grep slipbox.cluster-detection
# Should show: - 0 com.slipbox.cluster-detection
# Check logs
cat /tmp/slipbox-clusters.log
# Reinstall if needed
./scripts/install-cluster-detection.sh --uninstall
./scripts/install-cluster-detection.shFile watcher not running
launchctl list | grep slipbox.watcher
# Should show: - 0 com.slipbox.watcher
# Check logs
cat ~/.local/share/mcp/slipbox/watcher.log
# Reinstall if needed
./scripts/install-file-watcher.sh --uninstall
./scripts/install-file-watcher.shUpgrading from ZETTELKASTEN_* environment variables
If you previously used ZETTELKASTEN_NOTES_DIR, ZETTELKASTEN_DATABASE_PATH, or other ZETTELKASTEN_* variables, they are no longer read. Rename them to their SLIPBOX_* equivalents:
Old | New |
|
|
|
|
|
|
|
|
|
|
The server logs a warning if old names are detected, but does not migrate them automatically.
Cluster report moved next to each vault's index
Older releases wrote one cluster report for every vault on the machine, at ~/.local/share/mcp/slipbox/cluster-analysis.json. Each vault now keeps its own cluster-analysis.json beside its SQLite index, so separate vaults no longer share clusters or dismissals. Set SLIPBOX_CLUSTER_REPORT_PATH to put it somewhere else.
The first time a vault has no report of its own, it checks the old shared file. It adopts that report, dismissals included, only if most of the notes listed in its clusters exist in the vault. Otherwise the vault starts fresh. The old file is never modified or deleted, so you can remove it yourself once each vault has its own report.
Install scripts are macOS-only
The scripts/install-cluster-detection.sh and scripts/install-file-watcher.sh scripts use launchctl and ~/Library/LaunchAgents/, which only exist on macOS. On Linux, you'll need to create equivalent systemd units or cron jobs manually. See the manual test commands in the relevant README sections to verify the underlying Python scripts work on your platform.
Default paths are relative to the working directory
If SLIPBOX_NOTES_DIR and SLIPBOX_DATABASE_PATH are not set, the server defaults to data/notes and data/db/zettelkasten.db relative to the current working directory. When running via Claude Desktop, the CWD may not be what you expect. Always set absolute paths in claude_desktop_config.json to avoid this.
Development
Setup
git clone https://github.com/jamesfishwick/slipbox-mcp.git
cd slipbox-mcp
uv venv && uv pip install -e ".[dev]"Testing
The project has three tiers of tests:
Tier | Count | Speed | Cost | Command |
Unit + integration | 219 | ~2s | Free |
|
Tool contract tests | 22 | ~0.5s | Free |
|
LLM evals | 28 | ~10min | ~$3-5 |
|
# Default: runs unit + contract tests (CI runs this)
pytest
# Run everything except LLM evals
pytest tests/ evals/tool_contracts/
# Run LLM evals (requires claude CLI authenticated)
pytest evals/llm/ -v
# Run LLM evals with a specific model
EVAL_MODEL=sonnet pytest evals/llm/ -v
# Lint
ruff check src/ evals/Unit tests cover internal logic -- services, repository, models, parsing.
Tool contract tests verify the MCP tool output format that the LLM sees -- parseable structure, chaining (create -> search -> get), and helpful error messages. These are deterministic and don't call any LLM.
LLM evals send prompts to an LLM via the claude CLI with the MCP server connected, then grade results by inspecting the database state (notes created, links made, tags applied). They test whether the LLM actually uses the tools correctly given the tool descriptions.
CI/CD
Branch protection: Direct pushes to main are blocked. All changes go through PRs.
Workflow | Trigger | Runner | What |
| Every PR + push to main | GitHub-hosted | Unit + contract tests, ruff lint + format |
| Opt-in (label or manual) | Self-hosted | 28 LLM evals via claude CLI |
| Push to | GitHub-hosted | release-please PR; on its merge, build + publish to PyPI |
The LLM eval suite is expensive (~$3-5, ~10 min) and self-hosted, so it never runs automatically. A path-based trigger can't distinguish a real prompt change from a cosmetic reformat. Run it deliberately when you change prompt or tool-description semantics:
Add the
run-llm-evalslabel to the PR. It runs, and re-runs on each push while the label is present.Or trigger it manually from the Actions tab (
workflow_dispatch).Or run it locally without the runner:
pytest evals/llm/ -v.
Without a label or manual dispatch, the job is skipped (no runner allocated, no cost).
Customizing the eval setup
If you don't want a self-hosted runner: remove .github/workflows/llm-evals.yml and run pytest evals/llm/ -v locally before merging prompt changes.
If you want LLM evals on every PR automatically: add a pull_request trigger with the relevant paths: filter and drop the label gate in the job's if:. But expect incidental triggers from formatting-only edits.
To change the default eval model: Set EVAL_MODEL in your environment or in the workflow file. Default is haiku for speed/cost.
To set up a self-hosted runner:
# Get a registration token
gh api repos/OWNER/REPO/actions/runners/registration-token -X POST -q '.token'
# Download and configure
mkdir -p ~/.github-runners/slipbox-mcp && cd ~/.github-runners/slipbox-mcp
curl -sL -o actions-runner.tar.gz https://github.com/actions/runner/releases/latest/download/actions-runner-osx-arm64-2.325.0.tar.gz
tar xzf actions-runner.tar.gz
./config.sh --url https://github.com/OWNER/REPO --token <TOKEN> --unattended
nohup ./run.sh &Releasing to PyPI
Releases are automated. The Release workflow (.github/workflows/release.yml) runs release-please on every push to main and publishes via PyPI Trusted Publishing (OIDC, so no API token is stored in repo secrets).
The flow (you never hand-edit a version or push a tag):
Land changes on
mainwith Conventional Commit messages (feat:→ minor bump,fix:→ patch,feat!:/BREAKING CHANGE:→ major). The repo's commit hooks already enforce this shape.release-please keeps a standing "release PR" open, accumulating the next version bump (in
src/slipbox_mcp/__init__.py) and theCHANGELOG.mdentries derived from those commits.When you're ready to ship, merge the release PR. That tags the release (
v<version>) and, in the same workflow run, builds the sdist + wheel, runstwine check, and publishes to PyPI.
So cutting a release is one click: merge the bot's PR. Nothing else.
Commit types decide the version. So type accurately. The bump is computed mechanically from the Conventional Commit prefixes since the last release, not from the size of the change. Reserve feat:/fix: for changes to the shipped package; use the non-releasing types for everything else:
Prefix | Version effect | Use for |
| minor (1.3.0 → 1.4.0) | new runtime capability in the package |
| patch (1.3.0 → 1.3.1) | bug fix in the package |
| major (1.3.0 → 2.0.0) | backwards-incompatible change |
| none | docs, tooling, CI, packaging, internal-only changes |
A batch of only non-releasing commits produces no release PR at all. The squash-merge title is the commit release-please reads, so the PR title's prefix is what counts. Label it for what the package gains, not for the effort spent.
One-time setup (already done for this repo, documented for forks):
On PyPI, register a pending trusted publisher for project
slipbox-mcp: Owner:jamesfishwick· Repository:slipbox-mcp· Workflow:release.yml· Environment:release. All four must match exactly.In GitHub, create an environment named
release(Settings → Environments). If you restrict its deployment refs, add a tag rulev*(a branch rule of the same name will not match the tag).
The version is defined once, in
src/slipbox_mcp/__init__.py(release-please bumps it; the# x-release-please-versionmarker tells it which line).pyproject.toml(dynamic = ["version"]) and the server'sserver_versionboth read from it, so there is nothing to keep in sync; the tag release-please cuts always matches the package version by construction.
To rehearse a build without publishing, run it by hand: python -m build && twine check dist/* (and twine upload --repository testpypi dist/* with a TestPyPI token to dry-run the upload).
Shared prompt constants
All tool descriptions and prompt templates live in src/slipbox_mcp/server/descriptions.py. Both the MCP server and the eval tests import from this single source of truth. If you change a prompt, the evals test whether the LLM still behaves correctly with the new wording.
Debug logging
SLIPBOX_LOG_LEVEL=DEBUG python -c "from slipbox_mcp.main import main; main()"CLI Tool
The slipbox command provides terminal access for mechanical operations:
slipbox status # Overview of notes, tags, orphans, pending clusters
slipbox search <query> # Find notes by text
slipbox clusters # Show pending structure note candidates
slipbox orphans # List unconnected notes
slipbox rebuild # Rebuild index (add --clusters to refresh cluster analysis)
slipbox export <id> # Export note markdown to stdout
slipbox tags # List all tags with usage countsInstall: pipx install --editable . (adds slipbox to your PATH)
Experimental: Slipbox as agent memory
An untested hypothesis, not a recommended setup. Everything above helps an agent manage your knowledge. This inverts it: the agent uses a slipbox as its own persistent memory across sessions, in place of native memory or a rules file.
The model has no memory between sessions, so the slipbox is the only channel one session leaves for the next. It writes briefings for a cold successor (a failure and why, a recurring constraint, a correction, a hard-won fact), tags them agent-memory, and searches that tag before acting. The bet is that a connected memory beats a flat rules file, because you retrieve it by traversal.
Three things to know first: namespace isolation is a tag convention, not enforced, so run it against a separate slipbox instance; "memory" is a misnomer, since nothing persists but the notes themselves; and the growth discipline is the unproven part, so expect sprawl on the first run. Full write-up and caveats: Slipbox as Agent Self-Memory.
Documentation
Doc | What's in it |
Note ID format, the five note types, and a one-page cheat sheet for the method. | |
Running the same workflow by hand in Obsidian, no agent involved. | |
How Slipbox's links map to | |
Which other tools can read and write the same vault. | |
The opt-in autonomy layer: auto-capture, cluster detection, and the agent-memory experiment. | |
A worked session showing the tools in use. |
Contributing
See CONTRIBUTING.md for setup instructions, coding standards, and how to submit changes.
Roadmap
See ROADMAP.md for planned features and future direction.
Sponsor
If slipbox-mcp is useful to you, consider sponsoring the project.
Acknowledgments
Slipbox started as a fork of zettelkasten-mcp by Peter J. Herrel (@diggy) and Entanglr. It has since been largely rewritten and extended, but its core data model still comes from that project: the note types, typed links and their inverses, and timestamp-based note IDs. Thanks to them for the foundation.
License
MIT
Available Tools
19 toolsslipbox_create_linkA
Create a semantic link between two notes.
Links are directional: source -> target. Use bidirectional=true for important relationships (automatically creates inverse link type).
Link Types:
reference: Generic "see also" connection
extends: Source builds upon target (inverse: extended_by)
refines: Source clarifies or improves target (inverse: refined_by)
contradicts: Source presents opposing view (inverse: contradicted_by)
questions: Source raises questions about target (inverse: questioned_by)
supports: Source provides evidence for target (inverse: supported_by)
related: Loose thematic connection (symmetric)
Best Practices:
Always add description explaining WHY notes are linked
Use bidirectional=true for substantive relationships
Create links immediately after creating notes
Args: source_id: ID of the source note (the note doing the linking) target_id: ID of the target note (the note being linked to) link_type: One of reference/extends/refines/contradicts/questions/supports/related description: Brief explanation of the relationship bidirectional: If true, creates inverse link from target to source
Inputs: source_id (required), target_id (required), link_type, description, +1 more. Returns: result
slipbox_create_noteA
Create a new atomic Zettelkasten note.
Each note should contain exactly one idea. After creating, immediately
link to related notes using slipbox_create_link.
Note Types:
- fleeting: Quick captures, unprocessed thoughts (process within 24-48 hours)
- literature: Ideas extracted from sources. REQUIRES at least one entry
in references (citation or URL). If you don't yet have the citation,
use 'fleeting' as a staging type and promote to 'literature' once
the source is attached.
- permanent: Refined ideas in the user's own words (the core of your Zettelkasten)
- structure: Maps organizing 7-15 related notes on a topic
- hub: Entry points into major knowledge domains
Authoring:
- Store `content` exactly as the user provided it. Do NOT rewrite,
expand, or restructure their words. Compose or refine content only
when explicitly asked (e.g. "draft", "refine", "make it standalone").
Best Practices:
- Title should express the idea in brief (understandable without reading content)
- A refined permanent note typically runs 3-7 paragraphs and stands
alone; match the length of what the user gave you, though — a
one-line capture stays one line.
- Use 2-5 specific tags; prefer existing tags when they fit
- Search first (slipbox_search_notes) to avoid duplicating existing notes
Args:
title: Concise title expressing the core idea
content: Full note content in markdown
note_type: One of fleeting/literature/permanent/structure/hub (default: permanent)
tags: Comma-separated tags, e.g. "poetry,revision,craft"
references: Newline-separated citations to external sources (e.g. "Ahrens, S. (2017). How to Take Smart Notes.
Inputs: title (required), content (required), tags, note_type, +1 more. Returns: result
slipbox_create_structure_from_clusterA
Create a structure note from a detected cluster.
Generates a structure note organizing all notes in the cluster, with bidirectional links to each member note.
Run slipbox_get_cluster_report first to see available clusters and their IDs.
Args: cluster_id: ID from cluster report (e.g. "jackson-mac-low-chance-operations") title: Override the suggested title (optional) create_links: Create bidirectional links to member notes (default: true)
Inputs: cluster_id (required), title, create_links. Returns: result
slipbox_delete_linkA
Delete a specific link from one note to another.
Unlike slipbox_remove_link, this tool returns an error if no link exists between the two notes.
Args: source_id: ID of the source note (the note containing the link) target_id: ID of the target note (the note being linked to)
Inputs: source_id (required), target_id (required). Returns: result
slipbox_delete_noteA
Delete a note permanently.
Warning: This also removes all links to and from this note. Consider updating note_type to "fleeting" instead if uncertain.
Args: note_id: The ID of the note to delete
Inputs: note_id (required). Returns: result
slipbox_dismiss_clusterA
Permanently dismiss a cluster from maintenance suggestions.
Use this when a cluster has been reviewed and determined not to need a structure note, or when the user doesn't want to be reminded about it.
Args: cluster_id: The cluster ID to dismiss (e.g. "poetry-craft-revision")
Inputs: cluster_id (required). Returns: result
slipbox_find_central_notesA
Find the most connected notes in the Zettelkasten.
Central notes have the most incoming and outgoing links, making them key hubs in your knowledge network. Good candidates for hub notes.
Args: limit: Maximum results (default: 10)
Inputs: limit. Returns: result
slipbox_find_orphaned_notesA
Find notes with no connections to other notes.
Orphaned notes represent unintegrated knowledge. Review these periodically to either link them to existing notes or identify candidates for deletion.
Inputs: no named parameters. Returns: result
slipbox_find_similar_notesA
Find notes similar to a given note.
Similarity is based on shared tags, common links, and content overlap. Useful for discovering connections you might have missed.
Args: note_id: ID of the reference note threshold: Minimum similarity score 0.0-1.0 (default: 0.3) limit: Maximum results (default: 5)
Inputs: note_id (required), limit, threshold. Returns: result
slipbox_get_all_tagsA
Get all tags in the Zettelkasten.
Returns alphabetically sorted list of all tags. Use this to find existing tags before creating new notes to maintain tag consistency across your knowledge base.
Inputs: no named parameters. Returns: result
slipbox_get_cluster_reportA
Get pending cluster analysis for structure note creation.
Clusters are groups of notes sharing tags but lacking a structure note. High-scoring clusters are good candidates for new structure notes.
Uses cached analysis by default. Set refresh=true to regenerate. Cluster analysis runs automatically via cron if configured.
Scoring factors:
Note count (7-15 is ideal, >15 is overdue)
Orphan ratio (more orphans = more urgent)
Internal link density (fewer links = needs structure)
Recency (recent activity = active domain)
Args: min_score: Minimum cluster score 0.0-1.0 (default: 0.5) limit: Maximum clusters to return (default: 5) include_notes: Include full note list per cluster (default: false) refresh: Force regeneration of cluster analysis (default: false)
Inputs: limit, refresh, min_score, include_notes. Returns: result
slipbox_get_linked_notesA
Get notes linked to or from a specific note.
Use this to explore the knowledge graph around a note.
Directions:
outgoing: Notes this note links TO
incoming: Notes that link TO this note
both: All connected notes in either direction
Args: note_id: ID of the note to explore from direction: One of outgoing/incoming/both (default: both)
Inputs: note_id (required), direction. Returns: result
slipbox_get_noteA
Retrieve a note by ID or title.
Returns full note content including metadata, tags, and links. Use this to read note contents before creating links or updates.
Args: identifier: Either the note ID (e.g. "20251217T172432480464000") or exact title
Inputs: identifier (required). Returns: result
slipbox_list_notes_by_dateA
List notes by creation or update date.
Useful for reviewing recent work or finding notes from a specific period.
Args: start_date: Start date in ISO format YYYY-MM-DD (optional) end_date: End date in ISO format YYYY-MM-DD (optional) use_updated: If true, filter by updated_at instead of created_at (default: false) limit: Maximum results (default: 10)
Inputs: limit, end_date, start_date, use_updated. Returns: result
slipbox_rebuild_indexA
Rebuild the database index from markdown files.
Use this if notes were edited outside the MCP server or if the database seems out of sync with the filesystem.
Inputs: no named parameters. Returns: result
slipbox_refresh_clustersA
Regenerate cluster analysis and save report.
Analyzes all notes for emergent clusters based on:
Tag co-occurrence (tags that frequently appear together)
Connection patterns (notes that link to each other)
Structure note coverage (which clusters already have structure notes)
Results saved to cluster-analysis.json next to the vault's SQLite index (or SLIPBOX_CLUSTER_REPORT_PATH when set)
Inputs: no named parameters. Returns: result
slipbox_remove_linkB
Remove a link between two notes.
Args: source_id: ID of the source note target_id: ID of the target note bidirectional: If true, removes links in both directions
Inputs: source_id (required), target_id (required), bidirectional. Returns: result
slipbox_search_notesA
Search for notes by text, tags, or type.
Searches across titles and content. Combine parameters for precise filtering.
Examples:
Search by topic: query="poetry revision"
Filter by tag: tags="craft,poetry"
Find structure notes: note_type="structure"
Combined: query="metaphor" tags="poetry" limit=5
Args: query: Text to search in titles and content (optional) tags: Comma-separated tags to filter by, e.g. "poetry,craft" (optional) note_type: Filter by type: fleeting/literature/permanent/structure/hub (optional) limit: Maximum results to return (default: 10)
Inputs: tags, limit, query, note_type. Returns: result
slipbox_update_noteA
Update an existing note.
Only provided fields are updated; omitted fields remain unchanged. Pass empty string for tags to clear all tags. Pass empty string for references to clear all references.
Constraint: notes with note_type='literature' must have at least one reference. If you are promoting a note to 'literature', pass the citation in references in the same call.
Args: note_id: The ID of the note to update title: New title (optional) content: New content (optional) note_type: New type: fleeting/literature/permanent/structure/hub (optional) tags: New comma-separated tags, or empty string to clear (optional) references: New newline-separated citations, or empty string to clear (optional)
Inputs: note_id (required), tags, title, content, +2 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools target a distinct resource/action, but slipbox_delete_link and slipbox_remove_link are near-duplicates that differ only in error behavior, and get_cluster_report with refresh=true overlaps with refresh_clusters. The descriptions clarify the differences, but an agent could still easily select the wrong tool.
Names consistently follow a slipbox_verb_noun pattern with clear domain vocabulary. Minor inconsistencies remain: delete_link vs remove_link use different verbs for the same logical operation, and search_notes sits alongside find_similar_notes, find_central_notes, and find_orphaned_notes.
At 19 tools, this is above the typical well-scoped range, but the extra surface is justified by distinct note CRUD, link management, graph analytics, and cluster maintenance features. It feels slightly heavy rather than bloated.
The server covers note and link lifecycles, search and tag discovery, graph analysis, and cluster-driven structure creation, so core Zettelkasten workflows are supported. Minor gaps exist, such as no dedicated list-all-notes tool and link edits requiring delete/recreate, but agents can work around them.
Maintenance
Related MCP Connectors
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Related MCP Servers
- AlicenseCqualityFmaintenanceAn MCP server that integrates the zk note-taking system with LLMs, enabling users to search, read, create, and manage notes. It provides tools for link analysis, tag management, and complex note queries to interact with local knowledge bases.51MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that treats Obsidian vaults as knowledge graphs, enabling AI agents to traverse wikilinks, assemble token-budgeted context, and search with backlink awareness.3 npm1MIT
- AlicenseNot gradedqualityCmaintenanceA local-first MCP server that gives AI assistants long-term memory by storing, searching, and recalling notes as Markdown files on your machine.4 npmMIT
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server that enables AI assistants to securely read, create, and modify notes in an Obsidian vault, with support for semantic search and web scraping.7,721 npmMIT