How to Generate a Free PDF from Claude Code Using Deckrun MCP

Published: 2026-03-19

Note: The hosted MCP endpoint described below is provisioned per engagement — see Access & Availability. The pip install deckrun-mcp local workflow works immediately against your own deployment. For hosted access, contact us.

This step-by-step guide walks you through configuring the Deckrun MCP server in Claude Code and generating a free, presentation-quality PDF — entirely from your terminal. No API key, no browser, no sign-up required.

Prerequisites

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools. Deckrun provides an MCP server so Claude can generate slide decks on your behalf — you describe what you want, Claude writes the slides and calls the Deckrun API, and you get back a PDF link.

Step 1: Add the Deckrun MCP server

Open your project directory in the terminal and create (or edit) a file called .mcp.json in the project root:

{
  "mcpServers": {
    "deckrun": {
      "type": "streamable-http",
      "url": "https://deckrun-mcp-free.agenticdecks.com/mcp/"
    }
  }
}

This tells Claude Code to connect to the hosted Deckrun MCP server. No local installation or dependencies needed.

You can verify the endpoint is live by visiting https://deckrun-mcp-free.agenticdecks.com/mcp/ in your browser — it returns the server metadata as JSON.

Alternative: run the MCP server locally

If you prefer a local setup, clone the public repo and point Claude Code at it:

git clone https://github.com/agenticdecks/deckrun-mcp.git
cd deckrun-mcp
pip install -r requirements.txt

Then use this .mcp.json instead:

{
  "mcpServers": {
    "deckrun": {
      "type": "stdio",
      "command": "python3",
      "args": ["deckrun_mcp_server.py"],
      "cwd": "/path/to/deckrun-mcp"
    }
  }
}

Step 2: Start Claude Code and confirm the connection

Launch Claude Code from your project directory:

claude

Once inside, type /mcp to open the MCP server management panel. You should see:

deckrun · ✔ connected

If it shows a connection error, check that your .mcp.json is in the project root and that you have internet access. You can also restart Claude Code to re-initialize the connection.

Step 3: Ask Claude to fetch the slide format

Before generating a deck, Claude needs to know the Deckrun Markdown syntax. Type:

Use the deckrun get_slide_format tool

Claude will call the get_slide_format MCP tool and display the full specification — layout tags, slide separators, heading conventions, and an example deck. This confirms the connection is working end to end.

Step 4: Generate your first PDF

Now ask Claude to create a deck. Be specific about what you want:

Create a 3-slide deck about AI-powered document generation using the deckrun MCP tool.
Slide 1: title slide with "AI Meets Documents" as the title.
Slide 2: three benefits of AI document generation.
Slide 3: a call to action to try Deckrun.

Claude will:

  1. Write the slides in Deckrun Markdown format, using layout tags like <!-- <title-slide /> --> and <!-- <title-content-slide /> -->
  2. Call the generate_slide_deck MCP tool with the completed Markdown
  3. Return the result, including a public PDF URL

You'll see output like this:

{
  "url": "https://storage.googleapis.com/deckrun-free-artifacts-.../deck.pdf",
  "slug": "fa3e05b7bf",
  "slides": 3,
  "warnings": [],
  "schema_version": "deckrun.v1"
}

Open the url in your browser — that's your generated PDF. The link is public and expires after 90 days.

Step 5: Iterate on your deck

You can refine the deck by giving Claude feedback in the same session:

Make the second slide a two-column layout. Left column: benefits for developers.
Right column: benefits for non-technical users.

Claude will rewrite the Markdown using the <!-- <two-content-slide /> --> layout tag and call generate_slide_deck again with the updated content. Each call produces a new PDF at a new URL.

What the Deckrun Markdown looks like

Here's an example of what Claude generates behind the scenes:

<!-- <title-slide /> -->

# AI Meets Documents

Powered by Deckrun

---

<!-- <title-content-slide /> -->

## Why AI Document Generation?

- Faster than manual slide creation
- Consistent formatting every time
- Works from any AI assistant via MCP

---

<!-- <title-content-slide /> -->

## Try Deckrun Today

Visit agenticdecks.com to get started.
No API key needed for free PDF generation.

Slides are separated by --- on its own line. The title slide uses # (H1); all other slides use ## (H2).

Slide layout reference

Deckrun supports these layout tags — place one at the top of each slide:

Tag Use for
<!-- <title-slide /> --> Title slide (first slide, uses # heading)
<!-- <title-content-slide /> --> Standard content slide
<!-- <section-header-slide /> --> Section divider
<!-- <two-content-slide /> --> Two-column layout
<!-- <title-only-slide /> --> Heading only, no body
<!-- <content-with-caption-slide /> --> Image with caption
<!-- <blank-slide /> --> Blank with chrome
<!-- <full-blank-slide /> --> Fully blank

Deckrun also supports background images, two-column image layouts, inline image positioning, embedded video clips, multilingual narration, and more. Watch the full layout walkthrough — this video was generated entirely by Deckrun from a single Markdown file:

All Deckrun Layouts — Video Walkthrough

Free tier limits

Limit Value
Max slides 10
Max Markdown size 50 KB
PDF expiry 90 days
Authentication None required
Watermark Included
Rate limit 10 requests/minute

Need more? Paid plans remove the watermark, support video and audio output, custom themes, and premium narration voices.

Troubleshooting

deckrun not showing as connected in /mcp?

Generation returned an error?

Using the local stdio server and it won't start?

Slow first response?

What's next