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

Installation

Install directly from GitHub using uvx:

uvx --from git+https://github.com/bndkts/molt-md-mcp molt-mcp

Or 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 workspace
MOLT_BASE_URL (optional) - API base URL (defaults to https://api.molt-md.com/api/v1; use http://localhost:8000/api/v1 for 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 Forbidden from the API

Available Tools

Read-Only Tools (Available with both key types)

health_check - Check if the molt-md API is available
get_metrics - Get database statistics (document and workspace counts)
read_doc - Read a document's decrypted content
- Supports partial fetches with lines parameter
- Returns JSON with metadata or plain markdown
read_workspace - Read a workspace's content (name and entries)
- Supports preview generation with preview_lines parameter

Write Tools (Require write key)

Document Operations

create_doc - Create a new encrypted document
- Returns document ID, write key, and read key
update_doc - Replace a document's entire content
- Supports optimistic locking with if_match (version ETag)
append_doc - Append content to the end of a document
- Supports optimistic locking with if_match
delete_doc - Permanently delete a document

Workspace Operations

create_workspace - Create a new workspace to bundle documents
- Returns 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 workspace
- Does 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-mcp

Testing

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-mcp

With 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-mcp

Security 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

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

molt-md-mcp