WordMcp — Microsoft Word MCP Server

AI 어시스턴트가 COM 자동화를 통해 Microsoft Word for Windows를 제어할 수 있게 해주는 MCP 서버입니다. 문서 열기, 텍스트 읽기 및 편집, 단락과 표 관리, 문서 속성 설정, PDF 내보내기를 지원합니다.

Windows 전용입니다. Microsoft Word가 로컬에 설치되어 있어야 합니다. 이 서버는 실제 응용 프로그램을 자동화하며 .docx 파일을 직접 구문 분석하지 않습니다.

요구 사항

Related MCP server: Word Document MCP Server

설치

dotnet tool install --global WordMcp.McpServer

그러면 도구가 mcp-word로 제공됩니다.

mcp-word --version
mcp-word --help

나중에 업데이트하거나 제거하려면:

dotnet tool update --global WordMcp.McpServer
dotnet tool uninstall --global WordMcp.McpServer

대신 아직 출시되지 않은 빌드를 실행하려면 로컬에서 pack한 후 출력 폴더에서 설치하세요:

dotnet pack src\WordMcp.McpServer\WordMcp.McpServer.csproj -c Release -o artifacts
dotnet tool install --global --add-source .\artifacts WordMcp.McpServer

설치하지 않은 경우

이 서버는 MCP 레지스트리에 io.github.trsdn/mcp-server-word로 등록되어 있습니다. 패키지를 직접 해석하는 클라이언트는 전역 도구를 유지하는 대신 요청 시 해당 버전을 가져오는 dnx를 통해 실행할 수 있습니다:

{
  "servers": {
    "word": {
      "type": "stdio",
      "command": "dnx",
      "args": ["WordMcp.McpServer@0.1.0", "--yes"]
    }
  }
}

클라이언트 구성

서버는 stdio를 사용합니다.

VS Code / GitHub Copilot

.vscode/mcp.json:

{
  "servers": {
    "word": {
      "type": "stdio",
      "command": "mcp-word"
    }
  }
}

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "word": {
      "command": "mcp-word"
    }
  }
}

Copilot CLI

copilot mcp add word --command mcp-word

개념

모든 작업은 세션(session) 안에서 실행됩니다. 세션은 하나의 Word 인스턴스와 하나의 열린 문서를 소유하며, word-a1b2c3d4e5f6g 같은 session_id로 식별됩니다.

file(open|create) ──► session_id ──► text / paragraph / table / document ──► file(save) ──► file(close)

• 경로는 절대 경로여야 합니다 (C:\Users\me\Documents\report.docx).

• 지원되는 입력 형식: .docx, .docm, .doc, .dotx, .dotm, .rtf.

• 문서가 Word에서 이미 열려 있으면 안 됩니다. WordMcp는 단독 액세스가 필요합니다.

• Word는 백그라운드에서 보이지 않게 실행되며 세션이 종료되면 함께 종료됩니다.

세션 서비스

세션은 일반적으로 MCP 서버 프로세스 내부에 존재하며 프로세스와 함께 소멸됩니다. WordMcp.Service.exe는 세션을 대신 보관하는 선택적 배경 데몬으로, 클라이언트가 다시 시작되어도 세션이 유지되고 여러 클라이언트가 세션을 공유할 수 있습니다:

WordMcp.Service.exe --daemon [--idle-minutes 30]   # listen until idle or stopped
WordMcp.Service.exe --status                       # what is it doing?
WordMcp.Service.exe --stop                         # save open documents and exit

편집 데몬을 수동으로 시작할 필요는 거의 없습니다. 데몬을 사용하도록 구성된 클라이언트는 요청 시 데몬을 시작합니다. 데몬이 수신 대기하는 파이프에는 사용자의 SID가 포함되고 해당 SID로 ACL이 설정되므로 세션이 계정 간에 공유되지 않습니다. 유휴 시간 동안 열린 세션이 없으면 데몬은 스스로 종료됩니다.

데몬 모드를 사용하려면 MCP 서버에 WORDMCP_SERVICE_MODE=daemon을 설정하세요. 그러면 모든 도구 호출이 서버 자체 프로세스가 아닌 데몬으로 전달됩니다. 이 설정이 없으면 서버는 세션을 자체 프로세스에 유지하며, 이는 단일 클라이언트에게 적합합니다. 두 번째 프로세스도 시작 대기 시간도 없습니다.

도구

Tools and functions each have an action parameter.

file — 세션 수명 주기

file(action: "open", path: "C:\\Users\\me\\Documents\\report.docx")
// → { "sessionId": "word-a1b2c3d4e5f6g", "fileName": "report.docx", ... }

text — 내용

문자 위치는 get과 find에서 얻은 것이며 Word 범위 오프셋입니다.

paragraph — 구조

단락 색인은 Word와 마찬가지로 1부터 시작합니다.

table — 표

document — 메타데이터 및 내보내기

image — 그림

field — 필드 및 목차

section — 구역 및 페이지 설정

header-footer — 머리글 및 바닥글

kind은 header 또는 footer를, type은 primary, first-page 또는 even-pages를 지정합니다.

style — 스타일

style_type은 paragraph, character, table, list를 선택합니다. 전체 스타일 목록을 보려면 list에 in_use_only: false를 전달하세요. 지역화된 Word에는 370개 이상의 항목이 있습니다.

style(action: "create", session_id: "...", name: "Callout", base_style: "Normal")
style(action: "modify", session_id: "...", name: "Callout",
      font_size: 11, bold: true, color: "#C00000", space_after: 12)

list — 글머리 기호 및 번호 매기기

end_index를 생략하면 작업은 start_index에만 적용됩니다.

list(action: "apply", session_id: "...", start_index: 2, end_index: 5, list_type: "number")
list(action: "set-level", session_id: "...", start_index: 3, end_index: 4, level: 2)
list(action: "restart", session_id: "...", start_index: 6)

comment — 검토 메모

add는 anchor_text가 내부 구문을 명시하지 않는 경우 전체 단락을 메모 대상으로 합니다. delete 후 인덱스가 변경되므로 두 번째 메모 삭제 전에 다시 목록을 확인하세요.

comment(action: "add", session_id: "...", paragraph_index: 4,
        text: "Source?", anchor_text: "fifteen percent")
comment(action: "list", session_id: "...", unresolved_only: true)

revision — 변경 내용 추적

accept/reject에서 중단을 생략하면 머레/바닥글을 포함한 전체 문서에 적용됩니다.

revision(action: "set-tracking", session_id: "...", enabled: true)
revision(action: "accept", session_id: "...")

bookmark — 안정적인 참조

이름은 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함할 수 있습니다. 책갈피는 문서의 다른 부분이 편집된 뒤에도 유지되므로, 문단 인덱스가 바뀐 후에도 특정 구절을 다시 가리키는 신뢰할 수 있는 방법이 됩니다.

bookmark(action: "add", session_id: "...", name: "Intro", paragraph_index: 2)
bookmark(action: "add", session_id: "...", name: "Growth",
         paragraph_index: 4, anchor_text: "fifteen percent")
bookmark(action: "get-text", session_id: "...", name: "Intro")

screenshot — 페이지 보기

레이아웃 문제(페이지 나눔, 표 너비, 이미지 배치, 머리글 위치)는 측정값보다 렌더링된 페이지에서 훨씬 쉽게 판단할 수 있습니다. PNG는 파일로 저장되고 경로가 반환됩니다. include_image: true를 추가하면 base64로 인라인 반환되기도 하는데, 이미지를 실제로 살펴봐야 할 때만 사용하는 것이 컨텍스트를 아낄 수 있습니다.

dpi의 기본값은 150입니다. 빠른 레이아웃 확인에는 96, 인쇄에 가까운 결과를 보려면 300을 사용하세요.

screenshot(action: "page", session_id: "...", page: 2)
screenshot(action: "page", session_id: "...", page: 1,
           output_path: "C:/temp/page1.png", dpi: 300, include_image: true)

응답

모든 도구는 JSON을 반환합니다. 실패는 전송 오류가 아닌 구조화된 페이로드로 보고됩니다.

{
  "success": false,
  "isError": true,
  "tool": "text",
  "action": "Replace",
  "errorType": "KeyNotFoundException",
  "errorMessage": "Session 'word-unknown' not found."
}

알려진 동작 및 주의 사항

• document(save-as)는 원본 파일도 저장합니다. Word에는 형식을 바꾸는 '다른 이름으로 복사' API가 없습니다. PDF 이외의 대상을 지정하면 서버는 SaveAs2(target)을 호출한 다음 SaveAs2(original)을 호출하므로, 보류 중인 변경 사항이 원본 파일에도 부수 효과로 저장됩니다. 부수 효과가 없는 내보내기가 필요하면 export-pdf를 사용하세요.

• 색상은 16진수 RGB (#0078D4)입니다. 서버가 Word에서 기대하는 BGR 값으로 변환합니다.

• 권리 보호 문서(IRM/AIP)는 Word가 시작되기 전에 거부됩니다.

• Word에서 열려 있는 문서가 세션을 차단합니다 — 먼저 닫으세요.

• Word 대화 상자는 자동화를 멈춥니다. 호출이 시간 초과되면 바탕화면에 열려 있는 대화상자를 확인하세요.

• 스타일 이름은 영어입니다. 기본 제공 스타일(Heading 1, Title, Table Grid, …)은 Word의 언어 독립적 스타일 ID로 변환되므로 지역화된 설치에서도 작동합니다. 그 외 다른 이름은 그대로 Word에 전달되며, 사용자 지정 및 지역화된 스타일에 사용하게 되는 방식입니다. Word는 스타일을 지역화된 이름(독일어 설치에서는 Überschrift 1)으로 보고한다는 점에 유의하세요 — 그래서 style(list)는 name과 english_name을 모두 반환하며, english_name이 있으면 그 값을 다시 보내면 됩니다.

• 기본 제공 스타일은 삭제할 수 없습니다. style(delete)는 Word의 일반 COM 오류를 그대로 전달하지 않고 명확한 메시지와 함께 거부합니다. 문단에 여전히 적용되어 있는 사용자 지정 스타일도 삭제할 수 없습니다. 해당 문단을 먼저 다른 스타일로 지정하세요.

• 새 문서는 Word를 거치지 않고 직접 작성됩니다. file(create)는 빈 .docx/.docm 패키지를 자체적으로 생성한 후 해당 문서를 엽니다. Word를 통해 문서를 만드는 대신 직접 생성하는 이유는 Microsoft 365에 로그인된 컴퓨터에서 AutoSave가 새 문서를 OneDrive 것으로 가져가 요청된 로컬 경로를 조용히 무시하기 때문입니다.

• 병합된 표 셀은 table(read)에서 빈 문자열로 반환됩니다.

• 이미지 크기는 픽셀이 아닌 포인트 단위입니다 (72 pt = 1 인치). lock_aspect_ratio를 false로 설정하지 않는 한 image(insert)와 image(resize)는 가로세로 비율을 유지하므로 width만 전달하면 높이도 함께 조정됩니다.

• image는 인라인 그림만 다룹니다. 떠 있는 도형, 텍스트 상자, 차트는 그대로 두어지며 image(list)에 나타나지 않으므로 해당 요소가 있어도 이미지 인덱스가 밀리지 않습니다.

• 목차에는 머리글 문단만 포함됩니다. 머리글 스타일이 없는 문서에서는 field(insert-toc)가 entry_count: 0을 반환합니다. paragraph(add|set-style)을 사용해 먼저 Heading 1/Heading 2를 적용한 뒤 field(update-toc)를 실행하세요.

• field(update-all)은 머리글과 바닥글도 함께 순회합니다. Word의 Document.Fields는 본문만 대상으로 하므로, 그렇지 않으면 페이지 번호가 갱신되지 않기 때문입니다.

• image(insert)에 캡션을 지정하면 Word의 캡션 번호를 사용합니다. 따라서 캡션은 Figure 1 <your text> 형식으로 나타나며(비영어 설치에서는 지역화됨) 그림 목록에 포함됩니다.

• 모든 측정값은 포인트 단위입니다. 페이지 여백도 포함됩니다 (1 cm = 28.35 pt, 1 inch = 72 pt).

• section(page-setup)은 여백보다 먼저 paper_size를 적용합니다. Word를 실행하는 컴퓨터에서 용지 크기를 바꾸면 여백이 다시 설정되기 때문입니다. section_index가 없으면 설정은 모든 섹션에 적용됩니다.

• 머리글과 바닥글은 섹션 간에 상속됩니다. 새 섹션에 아무것도 쓰지 않으면 이전 섹션의 머리글이 표시됩니다. header-footer(set)에 section_index를 지정하면 해당 연결이 자동으로 끊어지므로 섹션 1은 자신의 텍스트를 유지합니다.

• first-page 및 even-pages 머리글은 섹션 전환이 필요합니다. header-footer(set)는 DifferentFirstPage 또는 DifferentOddEvenPages를 자동으로 켜 주므로 설정할 필요가 없습니다. 이 옵션이 없으면 Word는 텍스트를 저장하지만 표시하지 않습니다.

• list(apply)는 기본적으로 새 목록을 시작합니다. continue_previous_list는 꺼져 있는데, 이는 이전의 다른 목록의 번호를 이어받는 것이 원하는 동작이 아닌 경우가 많기 때문입니다. 일반 문단으로 구분된 두 개의 번호 목록은 독립적으로 유지됩니다. Word가 어쨌든 병합하는 경우 list(restart)를 사용하세요.

• 수준이 뚜렷하게 렌더링되는 것은 개요 번호 목록뿐입니다. list(set-level)는 모든 목록에서 사용할 수 있지만, 일반 bullet 또는 number 목록은 모든 수준에서 같은 표식을 보여줍니다 — 그저 문단만 들여쓰기 됩니다.

• comment(resolve)는 Microsoft 365에서 자주 실패합니다. Word의 최신 주석 방식에서는 API를 통해 추가된 모든 주석을 미게시된 초안으로 취급하며, 초안은 완료로 표시할 수 없습니다. 서버는 이 점을 명확한 메시지로 보고하므로 대신 주석을 삭제하세요. comment(list)는 상태를 전혀 노출하지 않는 설치에서는 resolved: null을 반환합니다.

• 주석 및 변경 내용 인덱스는 이동합니다. 주석을 삭제하거나 단일 수정을 수락하면 인덱스 오른쪽의 항목들이 모두 번호가 바뀝니다. 따라서 이전 인덱스를 재사용하지 말고 두 호출 사이에 list를 다시 실행하세요.

• 인덱스 없는 revision(accept|reject)는 머리글과 바닥글도 순회합니다. Document.AcceptAllRevisions()와 일치 units와 함께 field(update-all)과 동일한 문제가 있습니다.

• 변경된 내용은 추적이 켜져 있는 동안에만 기록됩니다. revision(set-tracking)은 소급 적용되지 않습니다. 기록할 편집 전에 켜 두세요.

• 책갈피 이름은 Word에서 제한됩니다. 이름은 문자로 시작해야 하며 문자, 숫자, 밑줄만 사용 가능하고 최대 40자로 제한됩니다. 공백, 하이픈, 점, 비-ASCII 문자를 사용하면 Word 호출 전에 거부됩니다. 그렇지 않으면 Word가 일반 COM 오류로 실패하기 때문입니다.

• 책갈피는 전체 문단을 참조하는 안정적인 방법입니다. 모든 삽입에 대해 문단 인덱스는 변하지만 책갈피는 변하지 않습니다. 한 번만 지정해 두고 나중에 bookmark(get-text)으로 다시 읽으면 됩니다.

• 문단에 대한 bookmark(add)는 문단 표시를 제외합니다. 따라서 get-text은 마지막 줄바꿈 없이 텍스트를 반환합니다. 여러 문단에 걸친 책갈피는 사이에 있는 표시를 유지합니다.

• screenshot(page)는 PDF를 통해 렌더링합니다. Word에는 페이지를 이미지로 반환하는 API가 없으므로, 서버는 ExportAsFixedFormat을 사용해 렌더링할 페이지를 추출하고 래스터화합니다. 저장되지 않은 변경 내용은 포함되며, 임시로 만들어진 PDF는 완료 후 삭제됩니다.

• 페이지 번호는 재페이지 매김한 결과입니다. 자동화로만 편집한 문서는 만료된 페이지 수를 보고하므로 screenshot이 먼저 다시 페이지 매김합니다. 따라서 페이지 수는 열기 시점이 아니라 현재 레이아웃을 반영합니다.

소스에서 빌드하기

git clone https://github.com/trsdn/mcp-server-word.git
cd mcp-server-word
dotnet build WordMcp.sln -c Release
dotnet test WordMcp.sln --filter "Category!=RequiresWord"

프로젝트 구조

생성된 도구 계층

15개 도구 중 열네 개는 빌드 시 생성됩니다. src/WordMcp.Core/Commands 안의 명령 인터페이스가 통신 계약의 단일 근거가 됩니다.

• [ServiceCategory("section", "Section")]은 도구 클래스 WordSectionTool의 이름을 정합니다.

• [McpTool("section", Title = ..., Description = ...)]은 도구 이름과 모델이 읽을 프롬프트를 제공합니다.

• 각 메소드에 있는 [ServiceAction("page-setup")]은 생성된 WordSectionAction 열거형의 값이 됩니다.

• 인터페이스 매개변수에 대한 XML 문서는 MCP 스키마에 매개변수 설명으로 포함됩니다.

생성기는 모든 작업의 매개변수를 하나의 메서드로 병합하므로 일부 작업에만 있는 매개변수는 선택적 매개변수로 생성됩니다. API를 변경하려면 생성된 코드가 아니라 인터페이스를 수정하세요. file은 문서 하나를 다루는 것이 아니라 세션을 관리하므로 그대로 수동 유지됩니다.

src/WordMcp.McpServer/obj/generated 아래에서 생성된 코드를 확인할 수 있습니다. GeneratedToolContractTests의 테스트는 생성된 인터페이스를 인터페이스와 비교하므로, 클라이언트에 전달되기 전에 빌드가 실패합니다.

실제 Word이 필요한 테스트는 [Trait("Category", "RequiresWord")]로 표시되며 CI에서 제외됩니다. 통합 테스트 실패 시 고아가 된 WINWORD.EXE 프로세스가 남아 나중에 실행을 느리게 하거나 차단할 수 있습니다. 재실행 전에 Get-Process WINWORD | Stop-Process -Force로 정리하세요.

참고 자료

문제 해결

기여하기

버그 리포트와 기능 요청은 이슈 템플릿으로 접수해 주세요. 풀 리퀘스트는 환영합니다. CONTRIBUTING.md에는 빌드 방법, 테스트 스위트를 구성하는 두 부분을 실행하는 방법, 그리고 도구를 추가하는 데 필요한 요건이 설명되어 있습니다.

먼저 행동 강령을 읽어 주세요.

보안 버그에 대해 공개 이슈를 제기하지 마세요. — 보안 정책에 설명된 대로 비공개로 신고해 주세요.

라이선스

MIT — LICENSE를 참조하세요.