Reported issues for hustcc-mcp-mermaid

Pod holds 18 of 19 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to hustcc-mcp-mermaid.

Most discussed

Please release a Dockerized version

Please add the Docker version of this to the next release! This would make integration into non JS Environments much easier.

Read the thread · 2026-02-11 · open · external user · 2 comments

Bug: "STDIO MCP Server started" log in stdout breaks MCP protocol on Windows

Describe the bug When using mcp-mermaid with an MCP client (specifically "Antigravity" on Windows), the connection fails immediately with the following error:

Error: calling "initialize": invalid character 'S' looking for beginning of value

Root Cause Analysis The error occurs because the server outputs a plain text log message to stdout right after startup: STDIO MCP Server started

This violates the Model Context Protocol (MCP), which requires stdout to be reserved exclus

Read the thread · 2026-01-15 · closed · external user · 5 comments

[Feature Request] Add `outputType: "url"` to return editable & downloadable Mermaid links (SVG/PNG)

Summary

Currently, mcp-mermaid supports base64, file, svg, and mermaid output types. When used inside GitHub Copilot (GHCP) for VS Code or other MCP gateway environments, the base64 mode triggers this recurring error:

Request failed: 400 {"error":{"message":"missing required Copilot-Vision-Request header for vision requests","code":""}}

This happens because Copilot treats inline base64 images as "vision" inputs, but doesn't send the required header for tool-generated images.

Proble

Read the thread · 2025-11-11 · closed · outside contributor · 4 comments

[Bug] Dockerfile fails to build

I am trying to run this MCP server as a container. Cloned the repo and using the provided dockerfile, I ran docker build -t mcp-mermaid:latest . but it failed with the error below.

 => [2/4] WORKDIR /app                                                                                                                                                                                                                1.0s
 => [3/4] COPY . .                                                         

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/22) · 2025-11-07 · closed · outside contributor · 2 comments

### 在claude code中使用存在问题，无法成功保存png到本地（好像是返回了一个base64的数据）

这个问题如何解决呢？

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/16) · 2025-10-07 · closed · external user · 3 comments

### Generated image can't be saved by agent

In agent mode, I ask to generate images of my diagrams.
 It works, I can see cards with the "file.png" in output, but it's not enable to save this file by himself, event if I explicit ask him.
 I have to click on the download button.

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/15) · 2025-10-02 · closed · external user · 2 comments

### Not able to run on Arch Linux due to Playwright dependencies

Unfortunately playwright only supports debian and ubuntu so this mcp server breaks entirely on Arch Linux

I tried running it with the docker image built from the Dockerfile but I am getting this in Claude Code

`MCP ERROR (mcp-server-chart): SyntaxError: Unexpected token 'S', "STDIO MCP "... is not valid    │
│    JSON`

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/14) · 2025-09-28 · closed · external user · 5 comments

### Something wrong with the request

curl -X POST "http://localhost:3033/messages?sessionId=383027ca-17f3-4905-8f5f-aabbb90dcc3c" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "generate_mermaid_diagram",
    "params": {
      "mermaid": "graph TD; A-->B; B-->C;",
      "theme": "default",
      "outputType": "png"
    },
    "id": "1"
  }'
Accepted%   

event: message
data: {"jsonrpc":"2.0","id":"1","error":{"code":-32601,"message":"Method not found"}}

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/9) · 2025-08-17 · closed · external user · 2 comments

## Most recent

### MCP spec conformance: 5 requirement(s) violated (via @hasmcp/mcp-spec-test) — spec 2025-11-25

Running the server exactly as documented in the README (`npx -y mcp-mermaid`, default stdio transport) against the `@hasmcp/mcp-spec-test` conformance suite shows the process never answers a handshake request within 10 seconds and the suite reports it as exited — so the client never completes a handshake and every capability check downstream has to be skipped. This report covers the older of the two spec revisions the suite offered, `2025-11-25` (filed separately from the `2026-07-28` report bec

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/50) · 2026-08-24 · closed · external user · 0 comments

### MCP spec conformance: 10 requirement(s) violated (via @hasmcp/mcp-spec-test) — spec 2026-07-28

Running the server exactly as documented in the README (`npx -y mcp-mermaid`, default stdio transport) against the `@hasmcp/mcp-spec-test` conformance suite shows the process never answers a `server/discover` or `initialize` request within 10 seconds and the suite reports it as exited — so the client never completes a handshake and every capability check downstream has to be skipped. This report covers the newer of the two spec revisions the suite offered, `2026-07-28`.

## Conformance report

#

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/49) · 2026-08-24 · closed · external user · 0 comments

### mcpm install

**mcpm search finds but install fails.**

_mcpm has a warning but i left it in to be complete._ 

mcpm search mcp-mermaid                                                                                                                                                                                                                      
/opt/homebrew/Cellar/mcpm/2.15.0_2/libexec/lib/python3.14/site-packages/fastmcp/server/auth/providers/jwt.py:10: AuthlibDeprecationWarning: authlib.jose module is d

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/48) · 2026-07-10 · open · external user · 0 comments

### [update needed]latest docker image cant run with args warning `node: bad option`

docker image v0.2.3(8f1217b11502) still use
`CMD ["node" "build/index.js"]`

which make user must run like：
`docker run -p 1122:1122 susuperli/mcp-mermaid:latest` **`build/index.js`** `--transport streamable --port 1122`
if wanna use any args.

`ENTRYPOINT ["node", "build/index.js"]` is right.

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/47) · 2026-06-24 · open · external user · 0 comments

### LMStudio Setup

for Lmstudio setup:
please add this to the docs:

{ "mcp-mermaid": { "command": "npx", "args": [ "-y", "@peng-shawn/mermaid-mcp-server" ] } }


[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/45) · 2026-05-04 · closed · external user · 0 comments

### Server error '503 Service Temporarily Unavailable'

Hello,

Hope you're doing well.

I and my team are facing an issue while using the mermaid mcp, we sometimes get 503 server error '503 Service Temporarily Unavailable' and we do not know why this happens sometimes. Will attach a screenshot for the error. 

<img width="1400" height="832" alt="Image" src="https://github.com/user-attachments/assets/4c1635d0-2a43-44c9-9cd9-8e762c119a58" />

Would be pleased if somebody reached out urgently for this matter.

[Read the thread](https://github.com/hustcc/mcp-mermaid/issues/35) · 2026-02-20 · closed · external user · 0 comments

### Unknown diagram error

Hi,

I tried running your MCP server in VSCode using the sample Mermaid snippet from Mermaid Live Editor, but when I click the generated link, I get an “Unknown diagram error”.

Could you advise what I might be doing wrong?

Thanks!

Here’s what I used:

flowchart TD A[Christmas] -->|Get money| B(Go shopping) B --> C{Let me think} C -->|One| D[Laptop] C -->|Two| E[iPhone] C -->|Three| F[fa:fa-car Car]


Input

{ "mermaid": "flowchart TD\n A[Christmas] -->|Get m

Read the thread · 2026-02-02 · closed · external user · 0 comments

"STDIO MCP Server started" message breaks stdio communication with MCP clients

Problem

The server prints STDIO MCP Server started to stdout on startup, which breaks JSON-RPC communication. MCP clients expect only valid JSON on stdout.

Error in Claude Desktop (macOS):

Unexpected token 'S', "STDIO MCP "... is not valid JSON

Config:

{
  "mcpServers": {
    "mcp-mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ]
    }
  }
}

Potential Fix

silent the hello message
send them to another strea

Read the thread · 2025-11-14 · closed · external user · 1 comment

[Feature Request] Markdown Output Support and File Reference Architecture for Large-Scale Agent Workflows

Feature Requests for Agent Workflow Visualizations

I've been using mcp-mermaid successfully to generate sequence diagrams for multi-agent simulations, and it works great! However, I'd like to propose a few enhancements that would make it even more powerful for large-scale agent workflows.

1. 🎯 Markdown Output Support (High Priority)

Current Behavior:

outputType: "svg" returns raw SVG
outputType: "mermaid" returns Mermaid source code

Desired Enhancement: Add `

Read the thread · 2025-10-18 · closed · external user · 1 comment

[Feature Request] Markdown Output Support and File Reference Architecture for Large-Scale Agent Workflows

Feature Requests for Agent Workflow Visualizations

1. 🎯 Markdown Output Support (High Priority)

Current Behavior:

outputType: "svg" returns raw SVG
outputType: "mermaid" returns Mermaid source code

Desired Enhancement: Add `

Read the thread · 2025-10-15 · open · external user · 1 comment

The remaining reports are on the project's issue tracker.

Reported issues for hustcc-mcp-mermaid

Most discussed

Please release a Dockerized version

Bug: "STDIO MCP Server started" log in stdout breaks MCP protocol on Windows

[Feature Request] Add outputType: "url" to return editable & downloadable Mermaid links (SVG/PNG)

Summary

Proble

[Bug] Dockerfile fails to build

"STDIO MCP Server started" message breaks stdio communication with MCP clients

Problem

Potential Fix

[Feature Request] Markdown Output Support and File Reference Architecture for Large-Scale Agent Workflows

Feature Requests for Agent Workflow Visualizations

1. 🎯 Markdown Output Support (High Priority)

[Feature Request] Markdown Output Support and File Reference Architecture for Large-Scale Agent Workflows

Feature Requests for Agent Workflow Visualizations

1. 🎯 Markdown Output Support (High Priority)

[Feature Request] Add `outputType: "url"` to return editable & downloadable Mermaid links (SVG/PNG)