Add the local MCP server

6 min readUpdated Nov 4, 2026Since CLI 0.3.0

Builds on Install and Sign in and tokens.

The markdrop CLI includes a local MCP server, markdrop mcp. An AI app on your computer starts it and talks to it over standard input and output. Because it runs next to your files, your assistant can publish a 2 GB video or send a folder without passing the file through the conversation.

Use it alongside the hosted server: the hosted one works with documents in your account, the local one with files on your disk. Apps in the cloud, such as claude.ai and ChatGPT, can't use the local server.

Ask an AI app to publish and replace a video0:44

Set it up

#
  1. Install the CLI

    #

    Install markdrop 0.6.0 or later and check with markdrop --version. See Install the markdrop CLI.

    Earlier versions have fewer tools: 0.3.0 added the peer-to-peer tools, 0.4.0 the file tools, 0.5.0 the workspace tools and 0.6.0 the page tools.

  2. Create an API token

    #

    Publishing and replacing files need an API token, and so do the workspace and page tools. Create one at markdrop.in/settings/tokens. Sharing peer to peer works without it, but with a token your shares are listed under your account, where the hosted server's list_shares can see them.

    You can give the token to the server as MARKDROP_TOKEN in its configuration, as below, or run markdrop login once and leave env out. The server uses the same token for every tool: publishing, workspaces and listing your shares. If both are set, MARKDROP_TOKEN wins.

  3. Add the server to your app

    #

    Register it once, as markdrop-p2p. The app starts and stops it.

    bash
    claude mcp add markdrop-p2p -e MARKDROP_TOKEN=mdk_•••• -- markdrop mcp
    

    Start Claude Code and run /mcp: markdrop-p2p shows as connected. There's nothing to sign in to. Add --scope user to make it available in every project.

“command not found” or the server won't start

Desktop apps often start with a shorter PATH than your terminal. Put the full path from which markdrop (on Windows, where markdrop) in command, for example /opt/homebrew/bin/markdrop.

Don't commit a configuration file that contains your token. In a shared project, keep the token in your user configuration or use markdrop login instead.

What it can do

#
ToolWhat it doesToken
upload_filePublish a file from disk (up to 2 GB for video and audio) and return its linkYes
replace_fileSwap the file behind a link, keeping the link; the old version is keptYes
list_file_versionsA file's versions, newest firstYes
restore_file_versionMake an earlier version current againYes
get_file_infoSize, SHA-256, version, and video or audio detailsYes
list_workspacesYour workspaces, roles and custom domainsYes
list_foldersA workspace's folders, as paths upload_file takesYes
upload_page_imagePut an image file from disk into a page: inline, as its cover or as its iconYes
export_pageSave a page as a Markdown, HTML or zip file on this computerYes
share_filesShare files or folders peer to peer and return a markdrop.in/share linkNo
share_statusProgress of every share and download in this sessionNo
stop_shareStop a share, or cancel a downloadNo
receive_shareDownload a share link into a folder on this computerNo

Inputs and results for each tool are in MCP tools.

Publishing files

#

upload_file and replace_file work like markdrop upload and markdrop replace: the file is hashed, sent in parts and checked by Markdrop before it goes live, and nothing changes if the check fails. If the app cancels a long upload, calling the tool again with the same arguments resumes it. Apps that show progress get progress updates with the bytes sent.

New uploads are open to anyone with the link unless the assistant sets access to private, password or workspace. With workspace (and optionally folder), the file goes into one of your workspaces, and the link returned is on the workspace's custom domain when it has a live one. A file uploaded into a workspace with no access set gets workspace access: only the workspace's members can open it.

Pages and files on disk

#

The hosted server writes pages, but it can't read your disk. Two local tools fill that gap:

  • upload_page_image uploads a PNG, JPEG, GIF or WebP image (up to 10 MB) to a page you can edit and returns the Markdown that shows it, for the assistant to put in the page with the hosted server's tools. With set_as cover or icon it also becomes the page's cover or icon; with append it is added at the end of the page.
  • export_page saves a page you can open as a file: Markdown (the default), one HTML file, or a zip with its images, and with include_subpages its sub-pages too. It goes into ~/Downloads/Markdrop unless the assistant names a file or folder, and it doesn't replace an existing file unless asked to (overwrite).

Sharing peer to peer

#
  • share_files takes up to 100 paths. One file is sent as it is; several paths or a folder go as one zip, which markdrop get and receive_share unpack and a browser saves as a zip.
  • The link keeps working, for one recipient at a time, until the assistant calls stop_share or you close the AI app. Closing the app ends every share it started.
  • receive_share downloads into ~/Downloads/Markdrop unless you name another folder, and runs in the background; ask for share_status to follow it. It never overwrites a file: a clashing name becomes name (1).ext.

Safety

#

An AI app can be talked into calling a tool by text it reads: a web page, an issue, a file. The local server refuses well-known secret locations so a request like "share ~/.ssh" doesn't turn into a link to your keys:

  • Folders: ~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.azure, ~/.password-store, ~/.config/gcloud, ~/.config/gh, macOS Keychains and the desktop keyring
  • Files: .env files, .netrc, .npmrc, .pypirc, .git-credentials, .pgpass, ~/.docker/config.json, SSH private keys such as id_rsa and id_ed25519, and .pem, .p12, .pfx and keychain files
  • Folders that contain any of these, and paths that reach them through a symbolic link

This applies to share_files, upload_file, replace_file and upload_page_image. receive_share and export_page also won't save into those locations or into folders that start programs at login. receive_share removes leading dots from received names, and export_page refuses a file name that starts with a dot, so nothing can plant a dotfile such as ~/.zshrc.

The guard is a safety net, not a sandbox. Read what your assistant is about to publish or share before you approve the call. To turn the guard off, set MARKDROP_MCP_ALLOW_ANY_PATH=1 in the server's env.

Troubleshooting

#
  • Logs. The server writes its log to standard error, which your AI app collects in its MCP log. Standard output carries only the protocol.
  • "no Markdrop API token". The file, workspace or page tools found no token. Add MARKDROP_TOKEN to the server's env, or run markdrop login, then restart the server from your app.
  • A share link stopped working. Shares end when the AI app closes. Ask the assistant to share again.
  • Slow transfers. See Send and receive files; the same environment variables work in the server's env.
Did this page help?