Skip to main content
Glama

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

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 tools
append_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

    A4.2/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT