mcp-server-spreadsheet

mcp-server-spreadsheet

mcp-name: io.github.marekrost/mcp-server-spreadsheet

スプレッドシートファイル（.xlsx、.csv、.ods）の読み取りと書き込みを行う、データファーストの MCP サーバーです。

主な機能

• マルチフォーマット — Excel（.xlsx）、CSV（.csv）、OpenDocument（.ods）ファイルを、統一されたツールインターフェースで扱えます。
• デュアルモード — セル単位のワークブック操作と、DuckDB を活用した SQL クエリエンジンを、同じファイルに対して自由に組み合わせて使用できます。
• ワークブックの基本操作 — ワークシート、行、列、セル、検索を扱えます。
• データのみ — 既存の書式を保持しますが、読み書きするのは値のみです。
• ステートレス — 呼び出しごとに file と sheet を明示的に指定します。ハンドルやセッションは必要ありません。
• アトミック保存 — 一時ファイルに書き込んだ後、os.replace() で対象パスに置き換えます。
• 書き込み時の型変換 — 数値文字列は数値に変換され、それ以外はテキストになります。
• シートをまたいだ SQL — インメモリの DuckDB を介して、JOIN、GROUP BY、集計、サブクエリを実行できます。変更はファイルに書き戻されます。
• 単一シートのワークブックとしての CSV — CSV ファイルは default という名前のシートを1つ持つワークブックとして扱われます。

要件

• Python 3.10+

インストール

PyPI から（推奨）

ローカルのチェックアウトは不要です。MCP クライアントを設定するだけです（以下を参照）。

ソースから（開発用）

git clone https://github.com/marekrost/mcp-server-spreadsheet.git
cd mcp-server-spreadsheet
uv sync

使用方法

Claude Desktop

claude_desktop_config.json に追加します。

PyPI を使用する場合（推奨）：

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uvx",
      "args": ["mcp-server-spreadsheet"]
    }
  }
}

ローカルソースを使用する場合：

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-server-spreadsheet", "main.py"]
    }
  }
}

Claude Code

.mcp.json に追加します。

PyPI を使用する場合（推奨）：

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uvx",
      "args": ["mcp-server-spreadsheet"]
    }
  }
}

ローカルソースを使用する場合：

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-server-spreadsheet", "main.py"]
    }
  }
}

スタンドアロン（stdio トランスポート）

# PyPI
uvx mcp-server-spreadsheet

# Local source
uv run main.py

ディレクトリへのファイルアクセス制限（任意）

MCP_SPREADSHEET_ROOT を設定すると、すべてのパス引数を単一のディレクトリツリー内に制限できます。範囲外のパスは拒否され、エージェントに明確なエラーが返されます。

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uvx",
      "args": ["mcp-server-spreadsheet"],
      "env": { "MCP_SPREADSHEET_ROOT": "/home/me/spreadsheets" }
    }
  }
}

設定しない場合（デフォルト）は、サーバープロセスがアクセスできるすべてのパスが許可されます。

フォーマットに関する注意

フォーマット	シート	数式	型
.xlsx	複数	文字列として保持	ネイティブ（int、float、date、bool）
.ods	複数	保持されない	ネイティブ（int、float、date、bool）
.csv	1つ（default）	該当なし	読み込み時に推定（int、float、text）

CSV ファイルでは、シート管理ツール（add_sheet、delete_sheet、copy_sheet）を実行するとエラーになります。

ツール

ワークブック操作

ツール	説明
list_workbooks	ディレクトリ内のすべてのスプレッドシートファイルを一覧表示します（再帰検索なし）
create_workbook_file	新しい空のスプレッドシートファイルを作成します（拡張子に基づくフォーマット）
copy_workbook	既存のファイルを新しいパスにコピーします

シート操作

ツール	説明
list_sheets	ワークブック内のすべてのシート名を一覧表示します
add_sheet	新しいシートを追加します（名前と位置は任意）
rename_sheet	既存のシートの名前を変更します
delete_sheet	名前を指定してシートを削除します
copy_sheet	ワークブック内でシートを複製します（新しい名前と位置は任意）

データの読み取り

ツール	説明
read_sheet	シート全体を行として読み取ります（行・列の範囲指定は任意）
read_cell	B3 など、単一セルの値を読み取ります
read_range	A1:D10 など、矩形範囲を読み取ります
get_sheet_dimensions	使用範囲の行数と列数を取得します

データの書き込み

ツール	説明
write_cell	単一セルに値を書き込みます
write_range	指定したセルを開始位置として、2次元配列を書き込みます
append_rows	最後に使用されている行の後に行を追加します
insert_rows	指定位置に空白行または値を入力済みの行を挿入します（行は下に移動します）
delete_rows	インデックスで行を削除します（行は上に移動します）
clear_range	行や列を削除せずに、範囲内の値を消去します
copy_range	セルの範囲を別の場所にコピーします（別のシートへのコピーも可能）

列操作

ツール	説明
insert_columns	指定位置に空白列を挿入します
delete_columns	インデックスで列を削除します

検索

ツール	説明
search_sheet	値または正規表現パターンを検索し、一致するセル参照を返します

テーブルモード（SQL）

ツール	説明
describe_table	列名、推定された型、行数、サンプル値を調べます
sql_query	読み取り専用の SQL SELECT を実行します（シートをまたいだ JOIN、GROUP BY、集計、サブクエリをサポートします）
sql_execute	INSERT INTO、UPDATE、または DELETE FROM を実行し、変更をファイルに書き戻します

SQL の例：

-- Filter and sort
SELECT name, revenue FROM Sales WHERE status = 'Active' ORDER BY revenue DESC LIMIT 20

-- Cross-sheet JOIN
SELECT o.order_id, c.name FROM Orders o JOIN Customers c ON o.customer_id = c.id

-- Aggregate
SELECT department, COUNT(*) AS n, AVG(salary) AS avg FROM Employees GROUP BY department

-- Mutate
UPDATE Sales SET status = 'Closed' WHERE quarter = 'Q1' AND revenue < 1000
DELETE FROM Logs WHERE date < '2024-01-01'

スペースを含むシート名は、引用符で囲む必要があります：SELECT * FROM "Q1 Sales"。

テーブルが 1 行目から始まらないシート

3 つの SQL ツールはすべて、header_row と data_start_row を受け付けます。それぞれ整数（すべてのシートに適用）または {sheet_name: row} のマッピング（指定されていないシートにはデフォルトが適用）を指定できます。列名が 1 行目より下にある場合は header_row を使用し、ヘッダーとデータの間に単位を示す行などの余分な行がある場合は data_start_row を使用します。

# Header on row 3, data follows immediately
sql_query(file, 'SELECT * FROM "People"', header_row=3)

# Mixed workbook: People headers at row 3, Orders header at row 1 with a
# units row at row 2.
sql_query(
    file,
    'SELECT * FROM "Orders" o JOIN "People" p ON o.name = p.name',
    header_row={"People": 3, "Orders": 1},
    data_start_row={"Orders": 3},
)

sql_execute は変更を書き戻す際、header_row より上の行を保持します。

テストの実行

uv sync --group dev
uv run pytest

各ツールは、一時ディレクトリに生成された .xlsx、.csv、.ods のフィクスチャを使ってテストされます。

共通パラメーター

シート単位の各ツールは、次のパラメーターを受け付けます。

パラメーター	必須	説明
file	はい	スプレッドシートファイル（.xlsx、.csv、または .ods）へのパス
sheet	いいえ	シート名。デフォルトではワークブックの最初のシートが使用されます

すべての行・列インデックスは1 始まりです。セル参照には A1 形式（A1、$B$2）を使用します。