This MCP server exposes a tool to generate HTML slides from Markdown text by leveraging the mkslides command-line utility. It provides a simple, MCP-compatible interface so you can feed Markdown content and optional presentation settings (theme, syntax highlighting, and Reveal.js options) and receive a URL to the generated slides served locally. The workflow is ideal for integrating with MCP-enabled clients (e.g., Claude in VSCode) to quickly produce polished slide decks from notes or Markdown content.

To use it, configure the mdslides-mcp-local server in your MCP client settings as shown in the installation guide. Once running, you can invoke the available tool generate_slides by passing the Markdown content and optional configuration. The server will generate the slides using mkslides, serve them on a local HTTP server, and return a URL such as http://localhost:8080/latest/index.html that you can open in a browser. Supported options include slides_theme (e.g., black, white, night, dracula), slides_highlight_theme for code blocks, and revealjs_options to customize transitions and other Reveal.js settings.

Prerequisites

• Python 3.12 or higher
• mkslides installed and available in your PATH
• MCP client (e.g., Claude in VSCode)
• Docker (optional, for containerized deployment)

Install locally (recommended)

1. Clone the repository: git clone https://github.com/your-repo/mdslides-mcp-server.git cd mdslides-mcp-server
2. Create and activate a Python environment (optional but recommended): python -m venv venv source venv/bin/activate # on Windows use venv\Scripts\activate
3. Install the package in editable or standard mode: pip install .

   or for development with uv:

   uv sync

Run the server locally

1. Start the MCP server using the local Python entry point as configured in MCP settings:

   Depending on your setup, you might run the server directly or rely on uv to manage it.

   python src/mdslides_mcp_server/server.py

Containerized deployment (Docker)

1. Ensure Docker is installed and running.
2. Use the provided deployment script to build and run the container: ./deploy_mdslides_docker.sh

Configuration in MCP

• If using pip/local run: add a server entry like: { "mcpServers": { "mdslides-mcp-local": { "command": "python", "args": ["src/mdslides_mcp_server/server.py"], "disabled": false, "autoApprove": [] } } }
• If using Docker deployment: attach to the running container: { "mcpServers": { "mdslides-mcp-local": { "autoApprove": [], "disabled": false, "timeout": 60, "command": "docker", "args": ["attach", "mdslides-mcp-instance"], "transportType": "stdio" } } }

Tips and common issues:

• Ensure mkslides is installed and available in PATH; otherwise the server will fail when invoking CLI commands.
• If you change Reveal.js or highlight.js options, double-check the syntax in revealjs_options to avoid JSON parsing errors.
• The generated slides are served from a local output directory (e.g., ./mkslides_output); ensure this directory exists and is writable in the host environment when using Docker.
• For Docker deployments, the deploy script will create and mount the required output directory on the host and manage the container lifecycle.
• If the MCP client times out, consider increasing the timeout setting in your MCP configuration.
• This server focuses on translating Markdown to HTML slides using mkslides; advanced customization should be done via mkslides options and Reveal.js configuration.