{"id":51300634,"url":"https://github.com/adrianh-za/py-mcp-excel","last_synced_at":"2026-06-30T19:01:21.004Z","repository":{"id":362564344,"uuid":"1259751443","full_name":"adrianh-za/py-mcp-excel","owner":"adrianh-za","description":"A Python project that exposes Excel file information via the Model Context Protocol (MCP) and a FastAPI REST API. It allows reading Excel spreadsheets to extract sheet names, sheet counts, and column information with data types.","archived":false,"fork":false,"pushed_at":"2026-06-04T20:31:02.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T22:12:36.777Z","etag":null,"topics":["fastapi","fastmcp","mcp","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adrianh-za.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-04T20:27:46.000Z","updated_at":"2026-06-04T20:33:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adrianh-za/py-mcp-excel","commit_stats":null,"previous_names":["adrianh-za/py-mcp-excel"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/adrianh-za/py-mcp-excel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianh-za%2Fpy-mcp-excel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianh-za%2Fpy-mcp-excel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianh-za%2Fpy-mcp-excel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianh-za%2Fpy-mcp-excel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adrianh-za","download_url":"https://codeload.github.com/adrianh-za/py-mcp-excel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianh-za%2Fpy-mcp-excel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34979578,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","fastmcp","mcp","python"],"created_at":"2026-06-30T19:01:20.301Z","updated_at":"2026-06-30T19:01:20.997Z","avatar_url":"https://github.com/adrianh-za.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Excel MCP and FastAPI Server\n\nA Python project that exposes Excel file information via the Model Context Protocol (MCP) and a FastAPI REST API. It allows reading Excel spreadsheets to extract sheet names, sheet counts, column information with data types, and sheet row data.\nThe point of the API is for easier testing, while the MCP server is the main focus for integration with MCP-compatible tools and agents.\n\n## Features\n\n- **MCP Server**: Model Context Protocol server with tools for Excel file inspection\n- **REST API**: FastAPI-based HTTP endpoints for programmatic access\n- **Excel Reader Library**: Core functionality for reading Excel files using pandas and openpyxl\n\n### Available Tools \u0026 Endpoints\n\n| Function | MCP Tool | API Endpoint | Description |\n|----------|----------|---------------|-------------|\n| Get sheet names | `read_sheet_names(path)` | `GET /api/excel/sheet-names?path={path}` | Returns list of sheet names in an Excel file |\n| Get sheet count | `read_sheet_count(path)` | `GET /api/excel/sheet-count?path={path}` | Returns the number of sheets in an Excel file |\n| Get columns with types | `read_columns(path, sheet, header_row=0)` | `GET /api/excel/columns?path={path}\u0026sheet={sheet}\u0026header_row={header_row}` | Returns column names and their data types from a specific sheet |\n| Read sheet rows | `read_sheet_data(path, sheet, rows_to_read=10, header_row=0)` | `GET /api/excel/sheet-data?path={path}\u0026sheet={sheet}\u0026rows_to_read={rows_to_read}\u0026header_row={header_row}` | Returns row data from a specific sheet as a list of value arrays |\n\n## Prerequisites\n\n- Python 3.14+\n- pip or uv for package management\n\n## Installation\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/adrianh-za/py-mcp-excel.git\ncd py-mcp-excel\n\n# Install dependencies using pip\npip install -e .\n\n# Or using uv\nuv pip install -e .\n```\n\n### Dependencies\n\n- `fastapi` - Web framework for the REST API\n- `mcp` - Model Context Protocol Python SDK\n- `openpyxl` - Excel file reading\n- `pandas` - Data manipulation and Excel parsing\n- `uvicorn` - ASGI server for FastAPI\n\n## Running the Project\n\n### REST API Server\n\nStart the FastAPI server:\n\n```bash\nPYTHONPATH=src uvicorn api_server.endpoints:app --host 127.0.0.1 --port 5251 --reload\n```\n\n```powershell\n$env:PYTHONPATH='src'; .\\.venv\\Scripts\\python.exe -m uvicorn api_server.endpoints:app --host 127.0.0.1 --port 5251 --reload\n```\n\nThe API will be available at:\n- **Swagger UI**: `http://localhost:5251/api/excel/swagger`\n- **OpenAPI JSON**: `http://localhost:5251/api/excel/openapi.json`\n- **ReDoc**: `http://localhost:5251/api/excel/openapi`\n\n### MCP Server\n\nStart the MCP server with your preferred transport:\n\n```bash\nPYTHONPATH=src python -m mcp_server.tools\n```\n\n**Optional Arguments:**\n- `--transport`: `stdio` (default) | `sse` | `streamable-http`\n- `--port`: `5250` (default)\n\nExamples:\n```bash\n# STDIO transport (default)\nPYTHONPATH=src npx @modelcontextprotocol/inspector python -m mcp_server.tools\n\n# Streamable HTTP transport\nPYTHONPATH=src python -m mcp_server.tools --transport streamable-http --port 5250\n\n# Server-Sent Events transport\nPYTHONPATH=src python -m mcp_server.tools --transport sse --port 5250\n```\n\n## MCP Inspector Configuration\n\nUse the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to test and interact with the MCP server.\n\n### Install and Run Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector\n```\n\n### Configuration for Streamable HTTP\n\n- **Transport Type**: `Streamable HTTP`\n- **URL**: `http://localhost:5250/mcp`\n- **Connection Type**: `Via Proxy`\n- **Authentication**: No custom headers or tokens required\n\n### Configuration for STDIO\n\n- **Transport Type**: `STDIO`\n- **Command**: `python`\n- **Arguments**: `-m mcp_server.tools` (with `PYTHONPATH=src` set in environment)\n- **Authentication**: No custom headers or tokens required\n\n### Configuration for SSE\n\n- **Transport Type**: `Server-Sent Events`\n- **URL**: `http://localhost:5250/sse`\n- **Authentication**: No custom headers or tokens required\n\n## API Usage Examples\n\n### cURL Examples\n\n```bash\n# Get sheet names from an Excel file\ncurl \"http://localhost:8000/api/excel/sheet-names?path=/path/to/file.xlsx\"\n\n# Get sheet count\ncurl \"http://localhost:8000/api/excel/sheet-count?path=/path/to/file.xlsx\"\n\n# Get columns with types from a specific sheet\ncurl \"http://localhost:8000/api/excel/columns?path=/path/to/file.xlsx\u0026sheet=Sheet1\"\n\n# Get columns with custom header row\ncurl \"http://localhost:8000/api/excel/columns?path=/path/to/file.xlsx\u0026sheet=Sheet1\u0026header_row=2\"\n\n# Read rows from a specific sheet\ncurl \"http://localhost:8000/api/excel/sheet-data?path=/path/to/file.xlsx\u0026sheet=Sheet1\u0026rows_to_read=10\u0026header_row=0\"\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianh-za%2Fpy-mcp-excel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadrianh-za%2Fpy-mcp-excel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianh-za%2Fpy-mcp-excel/lists"}