MarkItDown MCP Server — 工具人實驗室

🔧

工具人 Toolmen 出品

這個 MCP Server 是工具人實驗室自架的文件轉換服務，跑在 NAS3 上。
內網直連免密碼，外網用 Authorization: Bearer <NAS3密碼> 就好。
有問題找實驗室同學，或是直接問 Agent ——它比你更懂流程。

🚀

三步快速開始

把 MCP Server 加進你的 AI Agent，只需要三個步驟

加入 MCP Server 設定

在你的 AI 工具（Claude Desktop、Cursor 等）的設定檔中貼上 Server URL，選下方對應的設定格式。

上傳文件

Agent 會自動呼叫 upload_file 將文件以 base64 格式上傳到 NAS，或直接傳入 URL。

轉換 & 快取

Agent 呼叫 convert_to_markdown，即刻取得 Markdown 全文。結果自動存快取，下次直接取用。

⚙️

MCP 設定方式

根據你使用的 AI 工具，選擇對應的設定格式

實驗室內網免驗證

在實驗室的網路內（140.112.183.x / 192.168.23.x），不需要任何密碼。

{
  "mcpServers": {
    "markitdown": {
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp"
    }
  }
}

// .cursor/mcp.json
{
  "mcpServers": {
    "markitdown": {
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp"
    }
  }
}

// .gemini/antigravity-ide/settings.json
{
  "mcpServers": {
    "markitdown": {
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp"
    }
  }
}

// .gemini/settings.json
{
  "mcpServers": {
    "markitdown": {
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp"
    }
  }
}

// 在 AGENTS.md 中加入：
// ---
// 此專案使用 markitdown MCP server 讀取文件。
// MCP Endpoint: https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp
// 使用 check_cache → get_cached_markdown 或 upload_file → convert_to_markdown 流程。
// ---

// opencode.json
{
  "mcp": {
    "markitdown": {
      "type": "streamable-http",
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp"
    }
  }
}

外網存取需要密碼

在實驗室外部使用時，需要帶上 NAS3 密碼作為 Bearer Token。

{
  "mcpServers": {
    "markitdown": {
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp",
      "headers": {
        "Authorization": "Bearer <NAS3密碼>"
      }
    }
  }
}

// .cursor/mcp.json
{
  "mcpServers": {
    "markitdown": {
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp",
      "headers": {
        "Authorization": "Bearer <NAS3密碼>"
      }
    }
  }
}

// .gemini/antigravity-ide/settings.json
{
  "mcpServers": {
    "markitdown": {
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp",
      "headers": {
        "Authorization": "Bearer <NAS3密碼>"
      }
    }
  }
}

// .gemini/settings.json
{
  "mcpServers": {
    "markitdown": {
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp",
      "headers": {
        "Authorization": "Bearer <NAS3密碼>"
      }
    }
  }
}

// 在 AGENTS.md 中加入：
// ---
// 此專案使用 markitdown MCP server 讀取文件。
// MCP Endpoint: https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp
// 若收到 401，請向使用者詢問 NAS3 密碼，
// 加到 Authorization: Bearer <密碼> header。
// ---

// opencode.json
{
  "mcp": {
    "markitdown": {
      "type": "streamable-http",
      "url": "https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp",
      "headers": {
        "Authorization": "Bearer <NAS3密碼>"
      }
    }
  }
}

💡 外網連線時若收到 401 Unauthorized，Agent 會自動收到提示訊息，告訴它 NAS3 密碼即可，它會自行更新 header 重試。

🔧

可用工具一覽

Server 提供 8 個 MCP tools，Agent 連線後自動偵測並使用

upload_file

上傳檔案到 NAS（base64 編碼）。支援 PDF、DOCX、PPTX、XLSX 等格式。

convert_to_markdown

轉換文件為 Markdown。支援檔名、URL、data URI。自動存快取。

check_cache

檢查某文件是否已有 Markdown 快取，避免重複轉換浪費時間。

get_cached_markdown

讀取已快取的 Markdown 內容，直接取用不需重新轉換。

save_markdown

手動儲存 Markdown 快取，適用於需要手動管理的情境。

save_metadata

儲存文件轉換的 metadata（JSON），記錄來源、時間戳等資訊。

list_files

列出 NAS 上指定目錄（input / markdown / metadata）的檔案。

download_file

讀取 / 下載 NAS 上的檔案內容，可存到本地或直接在 Agent 內使用。

📝

Agent 指令範例

在你的 SKILL.md 或 .agents.md 裡加入以下指令，教 Agent 使用流程

完整 Skill 範例

# MarkItDown MCP — 文件轉換 Skill

## MCP Server
- Name: `markitdown`
- URL: `https://markitdown-mcp.toolmen.bime.ntu.edu.tw/mcp`
- Transport: Streamable HTTP

## 使用時機
當需要讀取、分析、摘要 PDF / DOCX / PPTX / XLSX 等文件時，使用此 MCP Server。

## 基本流程

### 首次轉換文件
1. 先呼叫 `check_cache(filename)` 檢查是否有快取
2. 若有快取 → 呼叫 `get_cached_markdown(filename)` 取得內容
3. 若無快取 → 呼叫 `upload_file(filename, content_base64)` 上傳文件
4. 然後呼叫 `convert_to_markdown(source=filename, save_cache=true)` 轉換
5. 轉換結果會自動存入快取

### 轉換網頁 URL
直接呼叫 `convert_to_markdown(source="https://example.com/doc.pdf")`

### 列出已有文件
呼叫 `list_files(target="input")` 或 `list_files(target="markdown")`

## 注意事項
- 上傳前需要將文件內容 base64 編碼
- 大於 10MB 的文件效率較差，考慮分段處理
- 快取會長期保留，不會自動過期
- 若連線時收到 401 Unauthorized，請向使用者詢問 NAS3 密碼，
  並在 MCP headers 中加入 `Authorization: Bearer <密碼>`

## 支援格式
`.pdf` `.docx` `.pptx` `.xlsx` `.csv` `.html` `.htm` `.txt` `.md` `.json`

精簡版（適合放在 .agents.md）

# 文件轉換

使用 `markitdown` MCP Server 讀取文件。

流程：
1. `check_cache(filename)` → 有快取就用 `get_cached_markdown(filename)`
2. 沒快取 → `upload_file` + `convert_to_markdown(source, save_cache=true)`
3. URL 轉換 → 直接 `convert_to_markdown(source="https://...")`

401 時詢問使用者 NAS3 密碼，加到 Authorization: Bearer header。

✅ Agent 連上 MCP Server 後會自動取得所有 tool 的描述和參數定義，通常不需要在 skill 裡重複寫每個 tool 的參數細節。上面的指令主要是教 Agent 什麼時候該用哪個 tool、以及使用順序。

🔄

運作流程

Agent、MCP Server、NAS 三者之間的互動時序

📥 首次轉換

Agent                          MCP Server                     NAS
  │                                │                              │
  ├─ upload_file(base64) ────────→ │                              │
  │                                ├─ decode & write ───────────→ │ /input/report.pdf
  │                                │                              │
  ├─ convert_to_markdown("report.pdf") ──→ │                      │
  │                                │  markitdown.convert()        │
  │                                ├─ save cache ───────────────→ │ /markdown/report.md
  │                                ├─ save metadata ────────────→ │ /metadata/report.json
  │  ←── Markdown content ─────────┤                              │
  │                                │                              │

📦 使用快取

Agent                          MCP Server                     NAS
  │                                │                              │
  ├─ check_cache("report.pdf") ──→ │                              │
  │  ←── has_cache: true ──────────┤  ← stat() ──────────────────│
  │                                │                              │
  ├─ get_cached_markdown() ──────→ │                              │
  │  ←── Markdown content ─────────┤  ← read() ─────────────────│
  │                                │                              │

📋

支援的檔案格式

幾乎涵蓋所有常見的文件格式

格式	副檔名	說明
PDF	`.pdf`	論文、報告、簡報 PDF
Word	`.docx`	Microsoft Word 文件
PowerPoint	`.pptx`	簡報檔
Excel	`.xlsx` `.csv`	試算表、資料表
HTML	`.html` `.htm`	網頁文件
文字	`.txt` `.md` `.json`	純文字、Markdown、JSON

❓

常見問題

遇到問題不慌，先看這裡

🔐 收到 401 Unauthorized 怎麼辦？

你可能在外網連線。請在 MCP 設定的 headers 裡加上 Authorization: Bearer <NAS3密碼>。密碼跟 NAS3 登入密碼相同，問實驗室同學即可。

🐢 大檔案上傳很慢？

因為 MCP 用 base64 傳檔案，會膨脹約 33%。大於 10MB 的文件建議直接用 URL 轉換（convert_to_markdown(source="https://...")），或考慮先放上 NAS 再用檔名轉換。

⏳ 快取會過期嗎？

不會自動過期。如果原始文件更新了，重新呼叫 convert_to_markdown(source, save_cache=true) 會覆蓋舊的快取。

🗂️ 舊的 SFTP / Filebase API 還能用嗎？

可以。MCP Server 和舊方案共用同一個 NAS 目錄（/mnt/nas3/Share/markitdown-filebase），檔案完全互通。但建議新的 Agent 直接用 MCP，更簡單。

MarkItDownMCP Server