Docs

Claude Code Setup

Connect Claude Code to your mdcrypt crypt in 4 steps. This enables Claude to read, create, and organize your notes directly from the terminal.

1. 1.Get your API key

   Log into mdcrypt, open Settings, and navigate to the API Access tab. Generate a new API key and copy it.

2. 2.Add MCP server config

   Add the following to your Claude Code MCP configuration file (~/.claude/mcp.json):

   {
     "mcpServers": {
       "mdcrypt": {
         "url": "https://mdcrypt.dev/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_API_KEY"
         }
       }
     }
   }

3. 3.Restart Claude Code

   Restart Claude Code or run /mcp to reload MCP servers. You should see mdcrypt listed as a connected server.

4. 4.Start using tools

   Claude now has access to 20 MCP tools. Try asking it to list your notes, create a new note, or search your crypt. Example prompts:

   • "List my recent notes"
   • "Create a note titled Meeting Notes with an ADR template"
   • "Add a D2 architecture diagram to my System Design note"
   • "Find all notes that link to my API Spec"

CLI Installation

Install the mdcrypt CLI for command-line access to your vault.

$npm install -g mdcrypt-cli
$mdcli config

CLI Commands

The CLI exposes your vault as Unix-friendly commands. Pipe, script, and compose them into your existing shell workflows.

mdcli ls                    # list recent notes
mdcli ls -l 50              # list last 50 notes
mdcli search "auth"         # full-text search
mdcli read <id>             # read a note (supports 8-char short IDs)
mdcli read <id> --raw       # raw markdown output (for piping)
mdcli create -t "Title"     # create a note
mdcli append <id> -c "..."  # append content to a note
mdcli rename <id> "New"     # rename a note
mdcli tag <id> api spec     # set tags on a note
mdcli backlinks <id>        # show notes linking to this note
mdcli rm <id>               # soft-delete a note
mdcli restore <id>          # restore a deleted note

mdcli folders               # list all folders
mdcli mkdir "Architecture"  # create a folder
mdcli mkdir "Sub" -p <id>   # create nested folder
mdcli mv <note_id> <folder> # move note to folder
mdcli rmdir <id>            # delete a folder

# Pipe git log into a release note
git log --oneline v1.0..HEAD | mdcli create -t "Release Notes v1.1" -c "$(cat -)"

# Search and read in one shot
mdcli read $(mdcli search "deploy" | head -1 | awk '{print $1}') --raw

# Daily standup note from template
mdcli create -t "Standup $(date +%Y-%m-%d)" --tag standup daily \
  -c "## Done\n\n## Doing\n\n## Blocked"

# Append CI results to a tracking note
echo "Build #$CI_BUILD_ID: $CI_STATUS" | mdcli append <id> -c "$(cat -)"

# Back up a note to local file
mdcli read <id> --raw > backup.md

# Bulk tag all notes matching a search
mdcli search "api" | awk '{print $1}' | xargs -I{} mdcli tag {} api docs

GitHub Sync

Sync your crypt bidirectionally with a GitHub repository. Notes are stored as Markdown files preserving your folder hierarchy.

$npm install -g mdcrypt-sync
$mdcrypt-sync config

mdcrypt-sync push           # push local crypt changes to GitHub
mdcrypt-sync pull           # pull remote changes into your crypt
mdcrypt-sync sync           # bidirectional sync (pull then push)
mdcrypt-sync watch          # continuous sync — watches for changes and syncs automatically

Other Agents

Any MCP-compatible agent can connect to mdcrypt. Use the same MCP server URL and API key configuration. The server uses StreamableHTTP transport and authenticates via Bearer token in the Authorization header.