Skip to main content
Glama
office_docs_mcp
by wkqco33

office_docs_mcp

CI License: MIT Python: 3.12+

LLM(대형 언어 모델)이 오피스 문서(Excel, Word, PowerPoint)를 안정적이고 토큰 효율적으로 읽고 쓸 수 있도록 지원하는 Model Context Protocol (MCP) 서버입니다.

버전 안내: 본 프로젝트는 현재 초기 개발 단계(0.y.z)이며, 사용자 피드백에 따라 도구 인터페이스가 지속적으로 개선되고 있습니다.


주요 기능

  • Excel (.xlsx, .xlsm):

    • excel_get_metadata: 시트 목록, 크기, 컬럼 요약 조회

    • excel_read_sheet: 지정된 행/열 범위(1-based)를 Markdown 테이블 또는 2차원 배열로 읽기 (수식/값 토글 지원)

    • excel_search: 워크시트 전체 또는 특정 시트의 셀에서 키워드 검색

    • excel_write_cell: 단일 셀(A1 등) 값/수식 쓰기 (backup=True 지원)

    • excel_write_range: 시작 셀부터 2차원 데이터 연속 기입 (backup=True 지원)

    • excel_append_rows: 시트 마지막 행 뒤에 데이터 추가 (backup=True 지원)

    • excel_manage_sheets: 시트 추가(add), 이름변경(rename), 복사(copy), 삭제(delete) (backup=True 지원)

    • excel_create_workbook: 새 빈 엑셀 파일 생성

  • Word (.docx):

    • word_get_outline: 문서 헤딩(제목) 목록 및 단락/표 개수 조회

    • word_read_paragraphs: 단락 슬라이싱 읽기 (0-based 페이징)

    • word_read_table: 표 내용을 Markdown 테이블 또는 2차원 배열로 읽기

    • word_search: 문서 내 단락 및 표 셀 대상 키워드 검색

    • word_append_paragraph: 문서 끝에 단락/헤딩 추가 (헤딩 레벨 자동 처리, backup=True 지원)

    • word_append_table_row: 특정 표에 새 행 추가 (backup=True 지원)

    • word_write_table_cell: 특정 표의 셀 텍스트 수정 (backup=True 지원)

    • word_replace_text: 문서 전체 텍스트 일괄/부분 치환 (backup=True 지원)

    • word_delete_paragraph: 특정 단락 삭제 (backup=True 지원)

    • word_create_document: 새 워드 문서 생성

  • PowerPoint (.pptx):

    • ppt_get_outline: 전체 슬라이드 수 및 각 슬라이드 제목/셰이프 요약 조회

    • ppt_read_slide: 특정 슬라이드의 텍스트 상자, 표, 발표자 메모 내용 추출

    • ppt_read_notes: 특정 슬라이드의 발표자 메모(Speaker Notes) 읽기

    • ppt_update_notes: 발표 대본/슬라이드 메모 작성 및 수정 (backup=True 지원)

    • ppt_search: 슬라이드 텍스트, 표, 발표자 메모 대상 키워드 검색

    • ppt_add_slide: 제목과 본문을 포함하는 새 슬라이드 추가 (backup=True 지원)

    • ppt_add_table: 슬라이드 내 표 생성 (backup=True 지원)

    • ppt_add_chart: 막대, 꺾은선, 원형 등 네이티브 수치 차트 생성 (backup=True 지원)

    • ppt_add_flowchart: Mermaid 문법 기반 편집 가능한 네이티브 플로우차트/아키텍처 다이어그램 생성 (backup=True 지원)

    • ppt_update_slide_text: 슬라이드 내 특정 셰이프 텍스트 수정 (backup=True 지원)

    • ppt_create_presentation: 새 프레젠테이션 파일 생성

  • MCP Prompts (@mcp.prompt()):

    • analyze_spreadsheet: 엑셀 데이터 구조 파악부터 심층 분석까지의 체계적 워크플로우 가이드

    • create_presentation_outline: 주어진 주제에 대한 슬라이드 구성 및 발표자 대본 작성 가이드

  • 안전한 파일 백업:

    • 모든 쓰기 도구에서 backup: bool = True 지정 시 수정 전 원본을 타임스탬프 백업 파일(.bak)로 자동 보관


Related MCP server: pharos-ai-doc-genie

시작하기

1. 요구 사항

  • Python >= 3.12

  • uv 패키지 관리자

2. 설치 및 가상환경 동기화

uv sync --group dev

3. CLI 명령어

# MCP 서버 실행 (기본 Stdio 트랜스포트)
uv run office-docs-mcp serve

# SSE 트랜스포트로 실행
uv run office-docs-mcp serve --transport sse

# 등록된 MCP 도구 목록 확인 (사람 가독형)
uv run office-docs-mcp tools

# 기계 판독용 단일 라인 목록
uv run office-docs-mcp tools --plain

# 기계 판독용 JSON 스키마 덤프
uv run office-docs-mcp tools --json

# 설정 관리 서브명령어 (각 플랫폼 기본 경로 표준 지원)
# - Linux: ~/.config/office_docs_mcp/config.toml ($XDG_CONFIG_HOME)
# - macOS: ~/Library/Application Support/office_docs_mcp/config.toml
# - Windows: %APPDATA%/office_docs_mcp/config.toml
uv run office-docs-mcp config show                  # 현재 병합된 설정 전체 확인 (JSON)
uv run office-docs-mcp config show --toml           # TOML 형식으로 확인
uv run office-docs-mcp config init                  # 플랫폼 기본 경로에 config.toml 생성
uv run office-docs-mcp config init --local          # 현재 작업 디렉토리에 ./config.toml 생성
uv run office-docs-mcp config path                  # 플랫폼 기본 설정 파일 경로 확인 (--json 지원)
uv run office-docs-mcp config path --local          # 로컬 설정 파일 경로 확인
uv run office-docs-mcp config set logging.level DEBUG # 플랫폼 설정 파일 키 변경
uv run office-docs-mcp config set --local logging.level DEBUG # 로컬 설정 파일 키 변경
uv run office-docs-mcp config get logging.level       # 특정 설정 값 조회

# 셸 자동완성 스크립트 생성
uv run office-docs-mcp completion bash > /etc/bash_completion.d/office-docs-mcp

4. MCP 클라이언트 연동 설정 (Copilot CLI, Claude Desktop, Antigravity agy, Cursor 등)

별도의 저장소 클론이나 사전 설치 없이 uvx를 통해 곧바로 연동할 수 있습니다:

GitHub Copilot CLI

저장소 루트의 .mcp.json에 Copilot CLI용 stdio 설정이 포함되어 있습니다. 이 저장소에서 Copilot CLI를 실행하면 폴더 신뢰를 승인한 후 office-docs 서버가 프로젝트별 MCP 서버로 자동 로드됩니다.

copilot

서버 상태와 도구 목록은 Copilot CLI에서 다음 명령으로 확인할 수 있습니다:

/mcp
/mcp show office-docs

사용자 전역 설정에 추가하려면 다음 명령을 실행합니다:

copilot mcp add office-docs -- uvx office-docs-mcp serve

프로젝트별 설정을 공유해야 하는 경우에는 현재 저장소의 .mcp.json을 커밋하는 방식을 사용하세요. tools: ["*"]는 이 서버의 모든 Excel, Word, PowerPoint 도구를 활성화합니다.

Antigravity CLI (agy) 및 Antigravity IDE / 2.0

  • 전역 설정 (모든 프로젝트에서 사용): ~/.gemini/config/mcp_config.json

  • 프로젝트별 로컬 설정: 프로젝트 루트의 .mcp.json

{
  "mcpServers": {
    "office-docs": {
      "command": "uvx",
      "args": ["office-docs-mcp", "serve"]
    }
  }
}

Claude Desktop 설정

claude_desktop_config.json에 동일하게 추가합니다:

{
  "mcpServers": {
    "office-docs": {
      "command": "uvx",
      "args": ["office-docs-mcp", "serve"]
    }
  }
}

환경 변수(env) 및 디버깅 옵션 설정 예시

MCP stdio 통신 시 stdout 오염을 방지하면서 디버그 로그를 파일에 기록하거나 설정을 커스텀할 수 있습니다:

{
  "mcpServers": {
    "office-docs": {
      "command": "uvx",
      "args": [
        "office-docs-mcp",
        "--log-level", "DEBUG",
        "--log-file", "/tmp/office_docs_mcp.log",
        "serve"
      ],
      "env": {
        "OFFICE_DOCS_MCP_LOGGING__LEVEL": "DEBUG",
        "OFFICE_DOCS_MCP_LOGGING__FILE": "/tmp/office_docs_mcp.log"
      }
    }
  }
}

로컬 개발 소스 디렉토리에서 연동할 경우:

{
  "mcpServers": {
    "office-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/office_docs_mcp",
        "run",
        "office-docs-mcp",
        "serve"
      ]
    }
  }
}

지원되는 환경 변수 및 CLI 옵션

분류

이름 / 플래그

설명

기본값 / 예시

환경 변수

OFFICE_DOCS_MCP_LOGGING__LEVEL

로깅 레벨 설정

INFO (DEBUG, INFO, WARNING, ERROR)

환경 변수

OFFICE_DOCS_MCP_LOGGING__FILE

서버 로그 출력 파일 경로

/path/to/office_docs_mcp.log

환경 변수

OFFICE_DOCS_MCP_APP__NAME

앱 식별자 이름

office_docs_mcp

환경 변수

XDG_CONFIG_HOME

기본 설정 파일 저장 디렉토리 (Linux)

~/.config

CLI 옵션

--log-level <LEVEL>

명령줄에서 로그 레벨 직접 지정

DEBUG, INFO 등

CLI 옵션

--log-file <PATH>

명령줄에서 로그 파일 경로 직접 지정

/path/to/logfile.log

CLI 옵션

-c, --config <PATH>

사용할 config.toml 경로 명시적 지정

~/.config/office_docs_mcp/config.toml

CLI 옵션

--no-color

터미널/로그 ANSI 색상 코드 비활성화

플래그

CLI 옵션

-t, --transport <stdio|sse>

MCP 전송 프로토콜 지정 (serve 명령어)

stdio

전체 설정 템플릿은 mcp.example.json 파일에서 확인하실 수 있습니다.

Pi 연동 (uvx)

Pi에서 MCP를 사용하려면 pi-mcp-adapter가 필요합니다. 이 저장소에는 Pi가 자동으로 읽는 프로젝트 설정 파일 .mcp.json이 포함되어 있습니다.

# 최초 1회
pi install npm:pi-mcp-adapter

# 저장소 루트에서 실행하면 .mcp.json을 자동으로 읽음
pi

# 또는 설정 파일을 명시
pi --mcp-config .mcp.json

Pi에서 /mcp로 office-docs 서버 상태를 확인하고, 설정을 변경한 뒤에는 /reload를 실행하세요. uvx가 PyPI에서 office-docs-mcp를 준비해 MCP stdio 서버를 실행하므로 별도 가상환경 활성화가 필요 없습니다. 서버는 첫 도구 호출 때 시작됩니다.

ncli로 사용 가이드 문서 추가

동일한 안내를 ncli 노트로 저장하려면 로그인 후 다음을 실행하세요.

ncli login
ncli add \\
  --title "Office Docs MCP를 Pi에서 uvx로 사용하기" \\
  --content-file docs/pi-mcp-ncli-guide.md \\
  --category other \\
  --no-input

자세한 절차는 docs/pi-mcp-ncli-guide.md를 참고하세요.


개발 및 테스트 (TDD)

# 전체 단위 및 통합 테스트 실행
uv run pytest -v

# 린트 및 코드 스타일 검증
uv run ruff check .
uv run ruff format --check .

자세한 기여 방법 및 개발 가이드는 아래 문서를 참고하세요:

Available Tools

29 tools
excel_append_rowsA

Append one or more rows to the end of an Excel sheet.

Args:
    file_path: Path to the Excel file.
    sheet_name: Target sheet name.
    rows: List of rows (each row being a list of cell values).
    backup: If True, create a backup of the original file before modifying.

Inputs: rows (required), file_path (required), sheet_name (required), backup. Returns: result

excel_create_workbookA

Create a new empty Excel workbook (.xlsx).

Args:
    file_path: Path where the new Excel file will be created.
    sheet_names: Optional list of sheet names to initialize. Defaults to ['Sheet'].

Inputs: file_path (required), sheet_names. Returns: result

excel_get_metadataA

Get metadata from an Excel workbook (.xlsx/.xlsm).

Returns sheet names, active sheet, dimensions (max rows/cols), and header preview.
Call this first before reading large sheets to inspect the structure.

Args:
    file_path: Absolute or relative path to the Excel file.

Inputs: file_path (required). Returns: object

excel_manage_sheetsA

Manage sheets in an Excel workbook (add, rename, delete, copy).

Args:
    file_path: Path to the Excel file.
    action: Action to perform: 'add', 'rename', 'delete', or 'copy'.
    sheet_name: Target sheet name.
    new_name: New name for the sheet (required for 'rename' and 'copy').
    backup: If True, create a backup of the original file before modifying.

Inputs: action (required), file_path (required), sheet_name (required), backup, +1 more. Returns: result

excel_read_sheetA

Read a rectangular cell range from an Excel sheet.

Indices are 1-based (row 1 is first row, col 1 is 'A').

Args:
    file_path: Path to the Excel file.
    sheet_name: Target sheet name (defaults to active sheet).
    start_row: Starting row index (1-based, inclusive, default 1).
    end_row: Ending row index (1-based, inclusive, default 50).
    start_col: Starting column index (1-based, inclusive, default 1).
    end_col: Ending column index (1-based, inclusive, default 20).
    evaluate_formulas: If True (default), returns calculated values. If False, returns raw formula strings.
    format: 'markdown' (default formatted table) or 'raw' (2D list of values).

Inputs: file_path (required), format, end_col, end_row, +4 more. Returns: result

excel_write_cellA

Write a value to a specific cell (e.g. 'A1', 'C10') in an Excel sheet.

Args:
    file_path: Path to the Excel file.
    sheet_name: Target sheet name.
    coordinate: Cell coordinate (e.g., 'A1', 'B5').
    value: The value to write (string, number, boolean, or formula like '=SUM(A1:A5)').
    backup: If True, create a backup of the original file before modifying.

Inputs: value (required), file_path (required), coordinate (required), sheet_name (required), +1 more. Returns: result

excel_write_rangeA

Write a 2D matrix of data starting from a designated top-left cell in an Excel sheet.

Args:
    file_path: Path to the Excel file.
    sheet_name: Target sheet name.
    start_cell: Top-left cell coordinate (e.g. 'A1').
    data: 2D array of rows and column values to write.
    backup: If True, create a backup of the original file before modifying.

Inputs: data (required), file_path (required), sheet_name (required), start_cell (required), +1 more. Returns: result

ppt_add_chartA

Add a native Excel-backed chart to a slide in a PowerPoint presentation.

Supported chart types:
- 'column_clustered', 'column_stacked', 'column_stacked_100'
- 'bar_clustered', 'bar_stacked', 'bar_stacked_100'
- 'line', 'line_markers', 'line_stacked'
- 'pie', 'pie_exploded', 'doughnut'
- 'area', 'area_stacked'

Args:
    file_path: Path to the PowerPoint file (.pptx).
    slide_idx: 0-based index of the slide.
    chart_type: Chart type name (e.g., 'column_clustered', 'line', 'pie', 'bar_clustered').
    categories: Category labels along the category axis (e.g. ['Q1', 'Q2', 'Q3', 'Q4']).
    series_data: List of series dicts, each with 'name' (str) and 'values' (list of numbers).
                 Example: [{'name': 'Revenue', 'values': [100, 120, 140, 160]}]
    title: Optional chart title.
    left: Left offset position in inches (default: 1.0).
    top: Top offset position in inches (default: 1.5).
    width: Chart width in inches (default: 8.0).
    height: Chart height in inches (default: 4.5).
    backup: If True, create a backup of the original file before modifying.

Inputs: file_path (required), slide_idx (required), categories (required), chart_type (required), +7 more. Returns: result

ppt_add_flowchartA

Add an editable flowchart or architecture diagram to a PowerPoint slide using Mermaid syntax.

Nodes are rendered as native PowerPoint shapes (Rounded Rectangles, Diamonds for conditions,
Ovals/Stadiums) connected by native connector arrows with arrowheads.
All text, colors, shapes, and layouts remain 100% editable inside PowerPoint.

Supported Mermaid Syntax:
- Direction: 'graph TD' / 'flowchart TD' (Top-Down), 'graph LR' / 'flowchart LR' (Left-Right)
- Box node: `NodeID[Node Label]`
- Rounded node: `NodeID(Node Label)`
- Condition/Decision node: `NodeID{Condition Label}`
- Stadium/Pill node: `NodeID([Label])`
- Line breaks in labels: `<br/>` or `\n`
- Arrows: `A --> B`, `A -->|label| B`, `A --- B`, `A ==> B`, `A -.-> B`
- Chain connections: `A --> B --> C`

Args:
    file_path: Path to the PowerPoint file (.pptx).
    slide_idx: 0-based index of the slide (auto-creates slide if presentation is empty).
    mermaid_code: Mermaid diagram code string.
    title: Optional slide title to display at the top.
    direction: Layout direction: 'auto' (detect from code), 'TD' (Top-Down), or 'LR' (Left-Right).
    left: Left margin offset in inches (default: 0.8).
    top: Top margin offset in inches (default: 1.6).
    width: Total width allocated for diagram in inches (default: 8.4).
    height: Total height allocated for diagram in inches (default: 5.0).
    backup: If True, create a backup of the original file before modifying.

Inputs: file_path (required), slide_idx (required), mermaid_code (required), top, +6 more. Returns: result

ppt_add_slideA

Add a new slide to a PowerPoint presentation (.pptx).

Args:
    file_path: Path to the PowerPoint file.
    title: Title for the slide.
    content: Optional content text for the body placeholder.
    layout_idx: Slide layout index (0=Title Slide, 1=Title and Content). Default 1.
    backup: If True, create a backup of the original file before modifying.

Inputs: title (required), file_path (required), backup, content, +1 more. Returns: result

ppt_add_tableA

Add a table to a specific slide in a PowerPoint presentation.

Args:
    file_path: Path to the PowerPoint file (.pptx).
    slide_idx: 0-based index of the slide.
    rows: Number of table rows.
    cols: Number of table columns.
    data: Optional 2D list of cell text values.
    left: Left offset position in inches (default: 1.0).
    top: Top offset position in inches (default: 2.0).
    width: Table width in inches (default: 8.0).
    height: Table height in inches (default: 4.0).
    backup: If True, create a backup of the original file before modifying.

Inputs: cols (required), rows (required), file_path (required), slide_idx (required), +6 more. Returns: result

ppt_create_presentationA

Create a new empty PowerPoint presentation (.pptx) with an optional title slide.

Args:
    file_path: Path where the presentation will be saved.
    title: Optional title for the first slide.

Inputs: file_path (required), title. Returns: result

ppt_get_outlineA

Get the outline of a PowerPoint presentation (.pptx).

Returns total slide count and slide-by-slide titles and shape counts.

Args:
    file_path: Path to the PowerPoint file.

Inputs: file_path (required). Returns: object

ppt_read_notesC

Read the speaker notes of a specific slide in a PowerPoint presentation.

Args:
    file_path: Path to the PowerPoint file (.pptx).
    slide_idx: 0-based index of the slide.

Inputs: file_path (required), slide_idx (required). Returns: result

ppt_read_slideA

Read all text content and table data from a specific slide in a PowerPoint presentation.

Args:
    file_path: Path to the PowerPoint file.
    slide_idx: 0-based index of the slide.

Inputs: file_path (required), slide_idx (required). Returns: object

ppt_update_notesA

Update speaker notes for a specific slide in a PowerPoint presentation.

Args:
    file_path: Path to the PowerPoint file (.pptx).
    slide_idx: 0-based slide index.
    notes_text: Text content to set as the speaker notes.
    backup: If True, create a backup of the original file before modifying.

Inputs: file_path (required), slide_idx (required), notes_text (required), backup. Returns: result

ppt_update_slide_textA

Update the text of a specific shape on a slide in a PowerPoint presentation.

Args:
    file_path: Path to the PowerPoint file.
    slide_idx: 0-based slide index.
    shape_idx: 0-based shape index within the slide.
    text: New text content for the shape.
    backup: If True, create a backup of the original file before modifying.

Inputs: text (required), file_path (required), shape_idx (required), slide_idx (required), +1 more. Returns: result

word_append_paragraphA

Append a paragraph or heading to the end of a Word document (.docx).

Args:
    file_path: Path to the Word document.
    text: Text to append.
    style: Optional style (e.g., 'Heading 1', 'Heading 2', 'List Bullet', or None for normal body).
    backup: If True, create a backup of the original file before modifying.

Inputs: text (required), file_path (required), style, backup. Returns: result

word_append_table_rowA

Append a new row of data to an existing table in a Word document.

Args:
    file_path: Path to the Word document.
    table_idx: 0-based index of the table.
    row_data: List of strings for each column in the new row.
    backup: If True, create a backup of the original file before modifying.

Inputs: row_data (required), file_path (required), table_idx (required), backup. Returns: result

word_create_documentA

Create a new empty Word document (.docx) with an optional title.

Args:
    file_path: Path where the document will be saved.
    title: Optional title text.

Inputs: file_path (required), title. Returns: result

word_delete_paragraphA

Delete a specific paragraph from a Word document by its 0-based index.

Args:
    file_path: Path to the Word document (.docx).
    paragraph_idx: 0-based index of the paragraph to delete.
    backup: If True, create a backup of the original file before modifying.

Inputs: file_path (required), paragraph_idx (required), backup. Returns: result

word_get_outlineA

Get the outline of a Word document (.docx).

Returns total paragraph count, table count, and all headings with their levels.

Args:
    file_path: Path to the Word document (.docx).

Inputs: file_path (required). Returns: object

word_read_paragraphsA

Read a chunk of paragraphs from a Word document (.docx).

Indices are 0-based.

Args:
    file_path: Path to the Word document.
    start_idx: Starting paragraph index (0-based, default 0).
    count: Number of paragraphs to retrieve (default 30).

Inputs: file_path (required), count, start_idx. Returns: result

word_read_tableA

Read a table from a Word document (.docx).

Args:
    file_path: Path to the Word document.
    table_idx: 0-based index of the table (default 0).
    format: 'markdown' (default) or 'raw' (2D list of cell text).

Inputs: file_path (required), format, table_idx. Returns: result

word_replace_textA

Find and replace text across paragraphs and tables in a Word document.

Args:
    file_path: Path to the Word document (.docx).
    find_text: Text string to find.
    replace_text: Replacement text string.
    count: Maximum number of replacements (-1 for all occurrences).
    backup: If True, create a backup of the original file before modifying.

Inputs: file_path (required), find_text (required), replace_text (required), count, +1 more. Returns: result

word_write_table_cellA

Update text in a specific cell of a table in a Word document.

Args:
    file_path: Path to the Word document.
    table_idx: 0-based index of the table.
    row_idx: 0-based row index.
    col_idx: 0-based column index.
    text: New text content for the cell.
    backup: If True, create a backup of the original file before modifying.

Inputs: text (required), col_idx (required), row_idx (required), file_path (required), +2 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 29 tools

    Disambiguation5/5

    Every tool is clearly namespaced by file type (ppt_, word_, excel_) and uses a specific verb_noun action, so an agent can immediately tell reading from writing, searching from metadata, and cell writes from row appends. Even similar operations like excel_write_cell and excel_write_range are distinct in scope.

    Naming Consistency5/5

    All tool names follow the same snake_case prefix_verb_noun pattern, with consistent prefixes per document type and consistent verbs like read, write, create, append, delete, and search. There is no mixing of camelCase, bare verbs, or unpredictable naming conventions.

    Tool Count4/5

    At 29 tools the set is larger than the typical ideal range, but the server intentionally spans three document ecosystems—PowerPoint, Word, and Excel—so roughly 8–11 tools per format is reasonable. Each tool addresses a distinct operation and none feel redundant, though the overall surface is on the heavier side.

    Completeness4/5

    The toolset covers core lifecycle operations for each format: create, read, search, write/update, and append/modify, with additional capabilities like charts, tables, notes, and sheet management. Minor gaps exist—such as no slide deletion, no Word table creation, and no Excel row deletion—but agents can typically work around these without dead ends.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers