Skip to main content
Glama
Alex5025

Document Converter MCP Server

by Alex5025
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

Document Converter MCP Server

這是一個 Model Context Protocol (MCP) server，用於在 Markdown 和 Word 文件之間進行轉換。它使用 pandoc 作為底層轉換引擎。

功能特色

  • 🔄 雙向轉換: 支援 Markdown 轉 Word 和 Word 轉 Markdown

  • ⚙️ 豐富選項: 支援多種 pandoc 轉換選項

  • 🔍 狀態檢查: 檢查 pandoc 安裝狀態和支援格式

  • 🛠️ 易於整合: 遵循 MCP 協議，易於與其他工具整合

Related MCP server: Pandoc Document Conversion

安裝需求

1. 安裝 pandoc

在 macOS 上，您可以使用 Homebrew：

brew install pandoc

或者從官方網站下載安裝程式： https://pandoc.org/installing.html

2. 安裝 Node.js 依賴

npm install

建置與執行

建置 TypeScript 代碼

npm run build

執行 MCP Server

npm start

當 MCP server 成功啟動時，您會看到：

Document Converter MCP Server 已啟動

開發模式（自動重建和重啟）

npm run dev

驗證 MCP Server 運行狀態

您可以使用以下方法確認 MCP server 正常運行：

  1. 檢查進程：

    ps aux | grep "node.*index.js"

  2. 測試功能：

    node test-conversion.js
node simulate-mcp-client.js

  3. 查看日誌：MCP server 會在 stderr 輸出狀態信息

可用工具

1. convert_markdown_to_word

將 Markdown 文件轉換為 Word (.docx) 文件。

參數:

  • inputPath (必需): Markdown 文件的完整路徑

  • outputPath (可選): Word 文件的輸出路徑

  • options (可選): 轉換選項

    • standalone: 產生完整文件 (預設: true)

    • toc: 產生目錄 (預設: false)

    • numberSections: 自動編號章節 (預設: false)

    • highlightStyle: 程式碼語法高亮樣式 (預設: "pygments")

2. convert_word_to_markdown

將 Word (.docx) 文件轉換為 Markdown 文件。

參數:

  • inputPath (必需): Word 文件的完整路徑

  • outputPath (可選): Markdown 文件的輸出路徑

  • options (可選): 轉換選項

    • extractMedia: 提取媒體文件到指定目錄

    • wrapText: 文字換行方式 ("auto", "none", "preserve")

    • atxHeaders: 使用 ATX 樣式標題 (預設: true)

3. check_pandoc_installation

檢查 pandoc 是否已安裝並顯示版本信息。

4. list_supported_formats

列出 pandoc 支援的所有輸入和輸出格式。

使用範例

轉換 Markdown 到 Word

{
  "tool": "convert_markdown_to_word",
  "arguments": {
    "inputPath": "/Users/alex/MCP_test/test.md",
    "outputPath": "/Users/alex/MCP_test/test.docx",
    "options": {
      "toc": true,
      "numberSections": true
    }
  }
}

轉換 Word 到 Markdown

{
  "tool": "convert_word_to_markdown",
  "arguments": {
    "inputPath": "/Users/alex/MCP_test/TDD 簡介拷貝.docx",
    "outputPath": "/Users/alex/MCP_test/TDD_intro.md",
    "options": {
      "extractMedia": "./media",
      "atxHeaders": true
    }
  }
}

整合到 MCP 客戶端

Claude Desktop

在 Claude Desktop 中使用此 MCP server，請按照以下步驟：

  1. 找到配置文件位置：

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. 添加 MCP server 配置：

{
  "mcpServers": {
    "document-converter": {
      "command": "node",
      "args": ["/Users/alex/MCP_test/dist/index.js"],
      "env": {}
    }
  }
}

  1. 重啟 Claude Desktop 以載入新的 MCP server

其他 MCP 客戶端

此 MCP server 遵循標準的 MCP 協議，可以與任何支援 MCP 的客戶端整合：

  • 命令: node

  • 參數: ["/Users/alex/MCP_test/dist/index.js"]

  • 通訊協議: stdio

  • 功能: 提供 4 個文件轉換工具

驗證整合

整合成功後，您應該能夠在 MCP 客戶端中看到以下 4 個可用工具：

  • convert_markdown_to_word

  • convert_word_to_markdown

  • check_pandoc_installation

  • list_supported_formats

支援的文件格式

此 MCP server 專門針對以下格式進行了優化：

  • 輸入: Markdown (.md), Word (.docx)

  • 輸出: Markdown (.md), Word (.docx)

pandoc 本身支援更多格式，您可以使用 list_supported_formats 工具查看完整列表。

故障診斷

常見問題

  1. "pandoc: command not found"

    • 確保已安裝 pandoc 並且在 PATH 中可用

    • 執行 which pandoc 檢查安裝位置

  2. "找不到輸入文件"

    • 確保文件路徑正確且文件存在

    • 使用絕對路徑以避免路徑問題

  3. 轉換失敗

    • 檢查輸入文件是否損壞

    • 確保您有寫入輸出目錄的權限

MCP 服務相關問題

  1. MCP server 無法啟動

    • 確保已執行 npm run build 建置項目

    • 檢查 Node.js 版本是否支援 ES modules

    • 查看終端錯誤信息以了解具體問題

  2. MCP 客戶端無法連接

    • 確認配置文件路徑正確

    • 檢查 MCP server 路徑 /Users/alex/MCP_test/dist/index.js 是否存在

    • 重啟 MCP 客戶端（如 Claude Desktop）

  3. 工具無法使用

    • 使用 node simulate-mcp-client.js 測試 MCP server 功能

    • 檢查 pandoc 是否正確安裝

    • 確認文件權限設置正確

調試方法

  • 測試 MCP server:

    cd /Users/alex/MCP_test
npm start

  • 測試轉換功能:

    node test-conversion.js

  • 模擬 MCP 客戶端:

    node simulate-mcp-client.js

檢查安裝

使用 check_pandoc_installation 工具驗證 pandoc 是否正確安裝。

MCP 服務管理

快速服務管理

使用提供的服務管理腳本來管理 MCP server：

# 啟動 MCP server
./mcp-service.sh start

# 檢查服務狀態
./mcp-service.sh status

# 查看實時日誌
./mcp-service.sh logs

# 停止服務
./mcp-service.sh stop

# 重啟服務
./mcp-service.sh restart

# 測試功能
./mcp-service.sh test

服務狀態檢查

執行 ./mcp-service.sh status 會顯示：

  • ✅ 服務運行狀態

  • 🔢 進程 ID (PID)

  • 💾 內存使用情況

  • 🔧 系統依賴檢查（pandoc、Node.js）

日誌管理

  • 服務日誌存儲在 mcp-server.log

  • 使用 ./mcp-service.sh logs 查看實時日誌

  • 日誌包含啟動信息和錯誤詳情

詳細整合指南

查看 MCP_INTEGRATION_GUIDE.md 了解：

  • Claude Desktop 配置步驟

  • 其他 MCP 客戶端整合

  • 故障排除和調試技巧

授權

MIT License

貢獻

歡迎提交 Issues 和 Pull Requests！

Available Tools

4 tools
check_pandoc_installationA

檢查 pandoc 是否已安裝並顯示版本信息

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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

The description discloses the basic behavior (check and display version) but does not specify what happens if pandoc is not installed, such as an error message or exit code. With no annotations, the description carries the full burden, but for a simple check it provides partial transparency.

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, front-loaded sentence with no extraneous content. Every word earns its place.

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

Completeness4/5

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

Given the tool's simplicity (no parameters, no output schema), the description is mostly complete. It could mention the behavior when pandoc is absent, but the core functionality is clearly conveyed.

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

Parameters4/5

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

There are no parameters, so the description does not need to explain any. The schema is empty, and the baseline for zero-parameter tools is 4.

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

Purpose5/5

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

The description clearly states the tool's function: checking if pandoc is installed and displaying the version. This specific verb+resource combination distinguishes it from sibling conversion tools.

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?

No explicit guidance on when to use this tool versus alternatives, but the purpose implies it's a prerequisite check for the conversion tools. It doesn't state exclusions or alternatives, but the context makes the usage clear.

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

convert_markdown_to_wordB

將 Markdown 文件轉換為 Word (.docx) 文件

ParametersJSON Schema
NameRequiredDescriptionDefault
optionsNoPandoc 轉換選項
inputPathYesMarkdown 文件的完整路徑
outputPathNoWord 文件的輸出路徑（可選，若未提供則使用相同檔名但副檔名為.docx）

TDQS

B3.4/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 full responsibility for behavioral disclosure. It only states the conversion action without mentioning side effects like file overwriting, dependency on Pandoc, or error behavior. This is a significant gap for a tool that reads and writes files.

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, well-structured sentence that states the core purpose without unnecessary filler. It is front-loaded and easy to understand.

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?

While the schema documents parameters well, the overall description lacks critical context such as prerequisite dependencies (Pandoc), file system side effects, and output behavior. This makes the tool incomplete for an agent to use safely and correctly without additional assumptions.

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?

The schema covers all parameters with descriptions and defaults, including the optional outputPath and the nested options object. The tool description itself does not add any additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

Purpose5/5

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

The description clearly states the tool's function: converting Markdown files to Word (.docx) files. It uses a specific verb and resource, and the opposite sibling (convert_word_to_markdown) makes the distinction obvious.

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 description implies usage through the name and description, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions or prerequisites. For example, it does not note that Pandoc must be installed, even though a sibling tool exists for that.

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

convert_word_to_markdownB

將 Word (.docx) 文件轉換為 Markdown 文件

ParametersJSON Schema
NameRequiredDescriptionDefault
optionsNoPandoc 轉換選項
inputPathYesWord 文件的完整路徑
outputPathNoMarkdown 文件的輸出路徑（可選，若未提供則使用相同檔名但副檔名為.md）

TDQS

B3.4/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 intent without mentioning dependencies (e.g., Pandoc), side effects, output behavior, or what happens to media files — significant gaps for correct usage.

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, direct sentence with no filler, clearly stating the core function in a compact manner. Every word serves a purpose.

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?

Given the tool has a nested options object, no output schema, and no annotations, the description is too thin. It fails to explain what happens after conversion, whether Pandoc is required, or how optional parameters (e.g., outputPath, extractMedia) affect the result, leaving important context missing.

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?

The input schema provides descriptions for all three parameters (100% coverage), so the baseline of 3 applies. The tool description adds no additional parameter semantics beyond what the schema already documents.

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

Purpose5/5

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

The description clearly states the action ('轉換' - convert) and the resource ('Word (.docx) 文件' to 'Markdown 文件'), distinguishing it from sibling tools like convert_markdown_to_word (reverse direction) and check_pandoc_installation (dependency check).

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 description implies the tool is for converting Word documents to Markdown, and sibling names clarify alternatives, but there is no explicit when-to-use or when-not-to-use guidance, nor any mention of prerequisites or exclusions.

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

list_supported_formatsA

列出 pandoc 支援的所有格式

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/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. It only states the tool lists formats, but does not disclose whether this requires pandoc to be installed, what the return format looks like (e.g., a list of strings or a JSON object), or whether it can be called safely without side effects. This is a notable gap for an unannotated tool.

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, front-loaded Chinese sentence that conveys the essential purpose without any filler. Every word is informative and there is no redundant phrasing.

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

Completeness4/5

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

For a simple parameterless list tool, the description is nearly complete. It does not specify the output format, and no output schema exists to cover that, but the expected behavior (returning a list of format names) is strongly implied. The low complexity offsets the minor omission.

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

Parameters4/5

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

The tool has zero parameters, and the input schema is empty. The description adds no parameter details, but none are needed because there is nothing to configure. This aligns with the baseline of 4 for parameterless tools.

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

Purpose5/5

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

The description '列出 pandoc 支援的所有格式' clearly identifies the action (list), the resource (all formats supported by pandoc), and distinguishes this tool from the conversion and installation-checking siblings. It is specific and unambiguous.

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

Usage Guidelines4/5

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

The description makes the usage context clear: it is the tool for discovering which formats pandoc supports. It does not explicitly state when not to use it, but the sibling names (convert_markdown_to_word, etc.) imply a distinct purpose, so no conflict or exclusion is needed.

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. Dates show when Glama detected each change.

  1. 4 tool updatesv1.0.0
    • First observedcheck_pandoc_installation
    • First observedconvert_markdown_to_word
    • First observedconvert_word_to_markdown
    • First observedlist_supported_formats
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: two conversion tools reverse directions, and the two utility tools check installation and list formats. No ambiguity exists between any pair.

Naming Consistency5/5

All tool names use lowercase snake_case with a consistent pattern: convert_markdown_to_word and convert_word_to_markdown follow verb_noun structure, while check_pandoc_installation and list_supported_formats are clear imperative verbs. The naming is uniform and predictable.

Tool Count5/5

Four tools is well-scoped for a document converter server, covering both directions of conversion plus necessary utilities. The count is within the ideal 3-15 range and each tool earns its place.

Completeness4/5

The core conversion lifecycle (Markdown <-> Word) is fully covered, and the utility tools support setup and exploration. A minor gap is the lack of a generic conversion tool for other pandoc formats, but the server's explicit focus on Markdown and Word makes this acceptable.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Alex5025/Document-Converter-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server