molt-mcp
Enables AI assistants to read, create, update, and manage encrypted markdown documents and workspaces, allowing markdown files to be organized into an LLM-accessible knowledge base with support for partial fetches and version control.
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., "@molt-mcp read the latest meeting notes from my workspace"
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.
molt-mcp
A Model Context Protocol (MCP) server that provides LLM access to molt-md, an encrypted markdown document hosting service. Turn your markdown files into an LLM-accessible knowledge base by uploading them to molt-md and accessing them through this MCP server. Your AI assistant can read, update, and manage encrypted markdown documents organized in workspaces.
Features
Markdown → MCP Server - Organize your markdown files into LLM-accessible storage with workspaces (free while in beta)
Full API Coverage - Every molt-md endpoint exposed as an MCP tool
Encrypted Storage - End-to-end encryption with AES-256-GCM
Read/Write Key Support - Permission enforcement via the API's dual-key model
Workspace Management - Bundle and organize multiple documents
Partial Fetches - Efficient document previews with line-limited reads
Version Control - Optimistic concurrency control with ETag support
Related MCP server: vnsh-mcp
Installation
Install directly from GitHub using uvx:
uvx --from git+https://github.com/bndkts/molt-md-mcp molt-mcpOr install from source for development:
git clone https://github.com/bndkts/molt-md-mcp.git
cd molt-md-mcp
uv pip install -e .Configuration
Claude Desktop
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"molt-md": {
"command": "uvx",
"args": ["--from", "git+https://github.com/bndkts/molt-md-mcp", "molt-mcp"],
"env": {
"MOLT_API_KEY": "your-api-key-here",
"MOLT_WORKSPACE_ID": "your-workspace-id-here"
}
}
}
}Environment Variables
MOLT_API_KEY(required) - Your molt-md write key or read key (obtained by creating a document)MOLT_WORKSPACE_ID(optional) - Access documents through a specific workspaceMOLT_BASE_URL(optional) - API base URL (defaults tohttps://api.molt-md.com/api/v1; usehttp://localhost:8000/api/v1for local development)
Permission Model
The server passes your configured key to the molt-md API on every request:
Write key → All operations succeed (read + create + update + delete)
Read key → Read operations succeed; write operations return
403 Forbiddenfrom the API
Available Tools
Read-Only Tools (Available with both key types)
health_check- Check if the molt-md API is availableget_metrics- Get database statistics (document and workspace counts)read_doc- Read a document's decrypted contentSupports partial fetches with
linesparameterReturns JSON with metadata or plain markdown
read_workspace- Read a workspace's content (name and entries)Supports preview generation with
preview_linesparameter
Write Tools (Require write key)
Document Operations
create_doc- Create a new encrypted documentReturns document ID, write key, and read key
update_doc- Replace a document's entire contentSupports optimistic locking with
if_match(version ETag)
append_doc- Append content to the end of a documentSupports optimistic locking with
if_match
delete_doc- Permanently delete a document
Workspace Operations
create_workspace- Create a new workspace to bundle documentsReturns workspace ID, write key, and read key
update_workspace- Replace a workspace's content (name and entries)Supports optimistic locking with
if_match
delete_workspace- Permanently delete a workspaceDoes not delete referenced documents
Usage Examples
Basic Document Operations
User: Create a new document with the title "Meeting Notes"
Assistant: [Uses create_doc tool] → Returns doc ID and keys
User: Read that document
Assistant: [Uses read_doc tool with the doc ID]
User: Append a new section to the document
Assistant: [Uses append_doc tool]Workspace Management
User: Create a workspace called "Project Alpha" with these two documents
Assistant: [Uses create_workspace tool with document IDs and keys]
User: Show me a preview of all documents in the workspace
Assistant: [Uses read_workspace with preview_lines=1]Partial Fetches for Efficiency
User: Show me just the title of document xyz
Assistant: [Uses read_doc with lines=1 and as_markdown=true]Development
Setup
# Clone the repository
git clone https://github.com/bndkts/molt-md-mcp.git
cd molt-md-mcp
# Install dependencies
uv pip install -e .
# Run the server
molt-mcpTesting
With local molt-md API:
# Start the molt-md API server first (in another terminal)
cd /path/to/molt-md
cargo run # or your preferred method
# Create a test document to get keys
curl -X POST http://localhost:8000/api/v1/docs \
-H "Content-Type: application/json" \
-d '{"content": "# Test Document"}'
# Save the write_key and id from the response
# Run the MCP server
export MOLT_BASE_URL="http://localhost:8000/api/v1"
export MOLT_API_KEY="your-write-key-here"
npx @modelcontextprotocol/inspector molt-mcpWith production molt-md API:
# Create a test document to get keys
curl -X POST https://api.molt-md.com/api/v1/docs \
-H "Content-Type: application/json" \
-d '{"content": "# Test Document"}'
# Save the write_key from the response
# Run the MCP server
export MOLT_API_KEY="your-write-key-here"
npx @modelcontextprotocol/inspector molt-mcpSecurity Notes
Never commit API keys to version control
Keys are shown only once during document/workspace creation - save them securely
Read keys can be safely shared for read-only collaborators
Write keys provide full access - share only with trusted editors
Lost keys cannot be recovered - the content becomes permanently inaccessible
Architecture
This is a thin wrapper around the molt-md REST API:
FastMCP handles the MCP protocol and tool registration
httpx makes async HTTP requests with connection pooling
Environment config provides API key and optional workspace context
UUID validation and ETag formatting ensure correct API usage
Links
molt-md: https://molt-md.com
MCP Specification: https://modelcontextprotocol.io
FastMCP: https://github.com/jlowin/fastmcp
License
MIT License - see LICENSE file for details
Contributing
Contributions are welcome! Please open an issue or pull request on GitHub.
Built with ❤️ for the Model Context Protocol ecosystem
Available Tools
11 toolsappend_docA
Append content to the end of a document (separated by newline). Requires write key. The API will return 403 if a read key is used.
Args: doc_id: UUID of the document to append to content: Markdown content to append if_match: Optional - version ETag (e.g., 'v5') to prevent conflicts
Inputs: doc_id (required), content (required), if_match. Returns: result
create_docA
Create a new encrypted document. Returns the document ID and both write and read keys. IMPORTANT: Save these keys - they are shown only once!
Args: content: Initial markdown content for the document (optional)
Inputs: content. Returns: result
create_workspaceA
Create a new encrypted workspace to bundle multiple documents. Returns the workspace ID and both write and read keys. IMPORTANT: Save these keys - they are shown only once!
Args: name: Human-readable workspace name entries: Optional list of entries. Each entry should have: - type: "md" for documents or "workspace" for sub-workspaces - id: UUID of the document/workspace - key: Write or read key for the item
Inputs: name (required), entries. Returns: result
delete_docA
Permanently delete a document. This action cannot be undone. Requires write key. The API will return 403 if a read key is used.
Args: doc_id: UUID of the document to delete
Inputs: doc_id (required). Returns: result
delete_workspaceA
Permanently delete a workspace. This action cannot be undone. Referenced documents and sub-workspaces are NOT deleted. Requires write key. The API will return 403 if a read key is used.
Args: workspace_id: UUID of the workspace to delete
Inputs: workspace_id (required). Returns: result
get_metricsA
Get database statistics (total documents and workspaces count).
Inputs: no named parameters. Returns: result
health_checkA
Check if the molt-md API is available and responding.
Inputs: no named parameters. Returns: result
read_docB
Read a document's decrypted content.
Args: doc_id: UUID of the document to read lines: Optional - return only the first N lines (for previews) as_markdown: If True, return plain markdown; if False, return JSON with metadata
Inputs: doc_id (required), lines, as_markdown. Returns: result
read_workspaceA
Read a workspace's decrypted content (name and entries).
Args: workspace_id: UUID of the workspace to read preview_lines: Optional - include preview of first N lines for each document entry
Inputs: workspace_id (required), preview_lines. Returns: result
update_docA
Replace a document's entire content with new content. Requires write key. The API will return 403 if a read key is used.
Args: doc_id: UUID of the document to update content: New markdown content (replaces existing content) if_match: Optional - version ETag (e.g., 'v5') to prevent conflicts
Inputs: doc_id (required), content (required), if_match. Returns: result
update_workspaceA
Replace a workspace's entire content (name and entries). Requires write key. The API will return 403 if a read key is used.
Args: workspace_id: UUID of the workspace to update name: New workspace name entries: New list of entries (replaces existing entries) if_match: Optional - version ETag (e.g., 'v1') to prevent conflicts
Inputs: workspace_id (required), name (required), entries (required), if_match. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Every tool has a clearly distinct purpose with no ambiguity. Document operations (create, read, update, delete, append) and workspace operations (create, read, update, delete) are cleanly separated, while get_metrics and health_check serve unique administrative functions. The descriptions clearly differentiate between similar-sounding tools like update_doc vs append_doc.
All tools follow a consistent verb_noun pattern with snake_case throughout. Document tools use create/read/update/delete/append_doc, workspace tools use create/read/update/delete_workspace, and administrative tools use get_metrics and health_check. There are no deviations in naming conventions.
With 11 tools, this is well-scoped for a document/workspace management system. The count provides complete CRUD operations for both documents and workspaces, plus append functionality for documents and essential administrative tools. Each tool earns its place without redundancy.
The tool surface provides complete coverage for document and workspace management. For documents: create, read, update, delete, and append operations cover the full lifecycle. For workspaces: create, read, update, and delete operations. Administrative tools (health_check, get_metrics) provide necessary monitoring. No obvious gaps exist for this domain.
Maintenance
Related MCP Connectors
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Encrypted Markdown notes and team knowledge base. Search, read and write notes in vaults you allow.
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
Agent document workspace with wallet auth. Create, update and share markdown docs. By AutEng.ai
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to securely read and write to an Obsidian-compatible Markdown vault with per-agent access control, audit logging, and conflict resolution.Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to create, list, read, update, and restore encrypted shared workspaces so multiple agents and people can collaborate on the same living document through one link. Supports version-checked writes that prevent concurrent agents from silently overwriting each other, plus one-shot share and read tools for quick content exchange.19 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to create, read, update, list, restore and renew encrypted shared workspaces and one-shot links, so multiple agents and people can collaborate on the same versioned document through one URL. Content is encrypted client-side before upload, supports view-only sharing, and is deleted 24 hours after the last edit.19 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to create, read, update, list, restore and share encrypted workspace links whose contents are encrypted client-side and auto-deleted 24 hours after the last edit, so several agents and people can read and write one living document instead of passing copies around. Writes are version-checked, so concurrent agents cannot silently clobber each other's work.19 npmMIT