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:

1. FastMCP handles the MCP protocol and tool registration
2. httpx makes async HTTP requests with connection pooling
3. Environment config provides API key and optional workspace context
4. 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