Skip to main content
Glama
imaimai86

mermaid-to-jpeg-mcp

by imaimai86
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Cursor MCP Server - Markdown to JPEG Converter

A local Model Context Protocol (MCP) server for Cursor that enables converting Markdown files to JPEG images. This server supports both regular markdown content and Mermaid diagrams.

Features

  • Convert regular Markdown files to JPEG images

  • Convert Mermaid diagrams to JPEG images

  • Configurable image dimensions and quality

  • Automatic detection of Mermaid diagram syntax

  • Clean, styled output for regular markdown content

Related MCP server: Image-Gen-Server

Prerequisites

Make sure you have the following installed:

  • Node.js (v14 or later)

  • npm or yarn

  • ImageMagick (brew install imagemagick)

  • Mermaid CLI (npm install -g @mermaid-js/mermaid-cli)

Installation

  1. Clone or copy the project files to your desired location

  2. Install dependencies:

    npm install

Usage

Standalone Script

You can use the standalone script to convert markdown files:

# Convert markdown to JPEG
node md-to-jpeg.js input.md [output.jpeg]

# Convert using the original mermaid-only script
node generate-diagram.js input.md [output.png]

MCP Server

The MCP server provides two tools:

  1. convert_md_to_jpeg: Convert any markdown file to JPEG

  2. convert_mermaid_to_jpeg: Convert Mermaid diagrams to JPEG

MCP Server Configuration

To use with Cursor, add the following to your MCP configuration:

{
  "mcpServers": {
    "markdown-to-jpeg": {
      "command": "node",
      "args": ["/path/to/your/cursor-mcp/server.js"],
      "env": {}
    }
  }
}

Running the Server

Start the MCP server:

npm start

Or run directly:

node server.js

Tools Available

convert_md_to_jpeg

Convert a markdown file to JPEG image with customizable options.

Parameters:

  • input_file (required): Path to the input markdown file

  • output_file (optional): Path for the output JPEG file

  • width (optional): Width of the output image (default: 1200)

  • height (optional): Height of the output image (default: 800)

  • quality (optional): JPEG quality 1-100 (default: 90)

convert_mermaid_to_jpeg

Convert a Mermaid diagram file to JPEG image.

Parameters:

  • input_file (required): Path to the input mermaid file

  • output_file (optional): Path for the output JPEG file

Example Usage

Regular Markdown

# My Document

This is a sample markdown document with:

- **Bold text**
- *Italic text*
- `Code snippets`

## Code Block

```javascript
function hello() {
  console.log("Hello, world!");
}

This is a blockquote


### Mermaid Diagram

```markdown
```mermaid
graph TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    C --> D[Rethink]
    D --> B
    B ---->|No| E[End]

## Supported Formats

- **Input**: Markdown (.md), Mermaid diagrams
- **Output**: JPEG (.jpeg, .jpg)

## Dependencies

- `@modelcontextprotocol/sdk`: MCP SDK for server implementation
- `puppeteer`: For rendering HTML to images
- `marked`: Markdown parsing
- `@mermaid-js/mermaid-cli`: Mermaid diagram generation
- `imagemagick`: Image format conversion

## Troubleshooting

### Common Issues

1. **"mmdc command not found"**: Install Mermaid CLI globally
   ```bash
   npm install -g @mermaid-js/mermaid-cli

  1. "convert command not found": Install ImageMagick

    brew install imagemagick

  2. Puppeteer issues: Make sure Chrome/Chromium is installed and accessible

Testing

Test the conversion with a sample file:

npm test

Or create a test markdown file and run:

echo "# Test Document\n\nThis is a test." > test.md
node md-to-jpeg.js test.md

License

MIT License

Available Tools

2 tools
convert_md_to_jpegC

Convert a markdown file to JPEG image

ParametersJSON Schema
NameRequiredDescriptionDefault
scaleNoScale factor for mermaid diagrams (default: 2)
widthNoWidth of the output image (default: 2400)
heightNoHeight of the output image (default: 1600)
qualityNoJPEG quality (1-100, default: 95)
input_fileYesAbsolute path to the input markdown file
output_fileNoAbsolute path for the output JPEG file (optional)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the high-level conversion and does not mention whether an output file is always written, what happens when output_file is omitted, whether existing files are overwritten, or how mermaid diagrams inside the markdown are handled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clean sentence with no filler, so it is concise and front-loaded. It is slightly under-sized for a tool with six parameters and a sibling, but conciseness itself is strong.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without annotations or an output schema, the description should compensate by explaining invocation behavior, output defaults, and limitations; it does not. An agent cannot tell what happens when output_file is optional or whether mermaid diagrams are processed, leaving important operational gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters already carry their own descriptions. The tool description adds no additional parameter meaning, but with complete schema coverage the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a clear verb and resource: converting a markdown file into a JPEG image. It distinguishes itself from the sibling convert_mermaid_to_jpeg by naming markdown as the input, though it does not explicitly contrast the two tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to choose this tool over convert_mermaid_to_jpeg or when it would be inappropriate. The only implied usage signal is the phrase 'markdown file', which is not explicit enough to count as clear context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_mermaid_to_jpegB

Convert a mermaid diagram file to JPEG image

ParametersJSON Schema
NameRequiredDescriptionDefault
scaleNoScale factor for higher resolution (default: 2)
widthNoWidth of the mermaid canvas (default: 2400)
heightNoHeight of the mermaid canvas (default: 1600)
qualityNoJPEG quality (1-100, default: 95)
input_fileYesAbsolute path to the input mermaid file
output_fileNoAbsolute path for the output JPEG file (optional)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the conversion outcome and says nothing about default output naming, overwrite behavior, optional parameters, external dependencies, or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence that front-loads the core action and output format. There is no filler and no repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a straightforward conversion tool, the core operation is clear, and the schema covers parameters. However, with no output schema or annotations, the description leaves unspecified how the optional output_file behaves when omitted, which is relevant for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters are already documented with defaults and purpose. The tool description adds no parameter-level detail, but the schema adequately carries that burden, making the baseline score appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific conversion action, identifies the input resource as a mermaid diagram file, and specifies the output format as JPEG. The mention of 'mermaid' clearly distinguishes it from the sibling convert_md_to_jpeg, even though the sibling is not explicitly named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied by the description and tool name: use this tool when you have a Mermaid diagram file to convert to JPEG. However, there is no explicit guidance about when not to use it or when to choose the sibling convert_md_to_jpeg tool instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedconvert_md_to_jpeg
    • First observedconvert_mermaid_to_jpeg
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools target distinct input file types: markdown versus mermaid diagrams. Their names and descriptions make the difference immediately obvious, so there is virtually no risk of an agent selecting the wrong one.

Naming Consistency5/5

Both tools follow the identical verb_noun pattern: convert_<source>_to_jpeg. This consistency makes the tool set predictable and easy to extend with additional source formats.

Tool Count3/5

With only two tools, the server feels slightly thin even for a narrowly scoped conversion service. The count is borderline: it covers the two advertised input types but does not provide any auxiliary options or additional conversion formats that might be expected.

Completeness4/5

The core conversion workflows for markdown and mermaid files to JPEG are covered, which aligns with the server's apparent purpose. Minor gaps exist, such as lacking output customization options or batch processing, but these can be worked around by agents without fundamental failure.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers