+
+[](https://pypi.org/project/excel-mcp-server/)
+[](https://pypi.org/project/excel-mcp-server/)
+[](https://opensource.org/licenses/MIT)
+
[](https://mseep.ai/app/haris-musa-excel-mcp-server)
# Excel MCP Server
@@ -20,72 +28,48 @@ A Model Context Protocol (MCP) server that lets you manipulate Excel files witho
- Python 3.10 or higher
-### Installation
-
-1. Clone the repository:
-```bash
-git clone https://github.com/haris-musa/excel-mcp-server.git
-cd excel-mcp-server
-```
-
-2. Install using uv:
-```bash
-uv pip install -e .
-```
-
### Running the Server
The server supports two transport modes: stdio and SSE.
-#### Using stdio transport (default)
+#### Using stdio transport
Stdio transport is ideal for direct integration with tools like Cursor Desktop or local development, which can manipulate local files:
```bash
-excel-mcp-server stdio
+uvx excel-mcp-server stdio
```
#### Using SSE transport
-SSE transport is perfect for web-based applications and remote connections, which manipulate remote files:
+SSE transport is perfect for remote connections, which manipulate remote files:
```bash
-excel-mcp sse
-```
-
-You can specify host and port for the SSE server:
-
-```bash
-excel-mcp sse --host 127.0.0.1 --port 8080
+uvx excel-mcp-server sse
```
## Using with AI Tools
-### Cursor IDE
-
-1. Add this configuration to Cursor, choosing the appropriate transport method for your needs:
+1. Add this configuration to your client, choosing the appropriate transport method for your needs:
**Stdio transport connection** (for local integration):
```json
{
"mcpServers": {
"excel-stdio": {
- "command": "uv",
- "args": ["run", "excel-mcp-server", "stdio"]
+ "command": "uvx",
+ "args": ["excel-mcp-server", "stdio"]
}
}
}
```
-**SSE transport connection** (for web-based applications):
+**SSE transport connection**:
```json
{
"mcpServers": {
"excel": {
"url": "http://localhost:8000/sse",
- "env": {
- "EXCEL_FILES_PATH": "/path/to/excel/files"
- }
}
}
}
@@ -93,25 +77,37 @@ excel-mcp sse --host 127.0.0.1 --port 8080
2. The Excel tools will be available through your AI assistant.
-### Remote Hosting & Transport Protocols
+## Environment Variables & File Path Handling
-This server supports both stdio and SSE transport protocols for maximum flexibility:
+### SSE Transport
-1. **Using with Claude Desktop:**
- - Use Stdio transport
+When running the server with the **SSE protocol**, you **must set the `EXCEL_FILES_PATH` environment variable on the server side**. This variable tells the server where to read and write Excel files.
+- If not set, it defaults to `./excel_files`.
-2. **Hosting Your MCP Server (SSE):**
- - [Remote MCP Server Guide](https://developers.cloudflare.com/agents/guides/remote-mcp-server/)
+You can also set the `FASTMCP_PORT` environment variable to control the port the server listens on (default is `8000` if not set).
+- Example (Windows PowerShell):
+ ```powershell
+ $env:EXCEL_FILES_PATH="E:\MyExcelFiles"
+ $env:FASTMCP_PORT="8080"
+ uvx excel-mcp-server sse
+ ```
+- Example (Linux/macOS):
+ ```bash
+ EXCEL_FILES_PATH=/path/to/excel_files FASTMCP_PORT=8080 uvx excel-mcp-server sse
+ ```
-## Environment Variables （for SSE transport）
+### Stdio Transport
-- `FASTMCP_PORT`: Server port for SSE transport (default: 8000)
-- `EXCEL_FILES_PATH`: Directory for Excel files (default: `./excel_files`)
+When using the **stdio protocol**, the file path is provided with each tool call, so you do **not** need to set `EXCEL_FILES_PATH` on the server. The server will use the path sent by the client for each operation.
## Available Tools
The server provides a comprehensive set of Excel manipulation tools. See [TOOLS.md](TOOLS.md) for complete documentation of all available tools.
+## Star History
+
+[](https://www.star-history.com/#haris-musa/excel-mcp-server&Date)
+
## License
MIT License - see [LICENSE](LICENSE) for details.
diff --git a/assets/logo.svg b/assets/logo.svg
new file mode 100644
index 0000000..273c5a8
--- /dev/null
+++ b/assets/logo.svg
@@ -0,0 +1,14 @@
+
\ No newline at end of file
diff --git a/src/excel_mcp/data.py b/src/excel_mcp/data.py
index e4e3117..dfe89b5 100644
--- a/src/excel_mcp/data.py
+++ b/src/excel_mcp/data.py
@@ -21,7 +21,7 @@ def read_excel_range(
) -> list[dict[str, Any]]:
"""Read data from Excel range with optional preview mode"""
try:
- wb = load_workbook(filepath, read_only=True)
+ wb = load_workbook(filepath, read_only=False)
if sheet_name not in wb.sheetnames:
raise DataError(f"Sheet '{sheet_name}' not found")
diff --git a/src/excel_mcp/workbook.py b/src/excel_mcp/workbook.py
index a759fe8..9d6f193 100644
--- a/src/excel_mcp/workbook.py
+++ b/src/excel_mcp/workbook.py
@@ -67,7 +67,7 @@ def get_workbook_info(filepath: str, include_ranges: bool = False) -> dict[str,
if not path.exists():
raise WorkbookError(f"File not found: {filepath}")
- wb = load_workbook(filepath, read_only=True)
+ wb = load_workbook(filepath, read_only=False)
info = {
"filename": path.name,
+