Spreadsheet Local

You run a local MCP (Model Context Protocol) server that fetches data from Google Sheets or Google Drive and exposes it to MCP clients through Stdio. This lets you query spreadsheet data directly from tools and clients that support MCP, without hosting a separate API.

How to use

Once the server is running, you can access it from your MCP client (for example Claude Desktop) as a local Stdio service. The server provides a tool called get_data that reads data from Google Sheets or Google Drive files, including Excel formats, and returns the results to your MCP client. Start the server, authenticate when prompted, and then issue get_data requests with the spreadsheet URL and optional sheet name to retrieve data.

How to install

Prerequisites: Node.js v18 or newer. A Google Cloud Platform (GCP) project with Google Sheets API and Google Drive API enabled, plus an OAuth 2.0 client ID.

Installation steps

# 1. Clone the project
git clone <repository-url>
cd spreadsheet_local_mcp_server

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env

# 4. Edit .env to set required values
PORT=8080
GOOGLE_REDIRECT_URI=http://localhost:8080/auth/callback

# 5. Build and start
npm run build
npm start

If the server is already authenticated (a tokens file exists), it starts in MCP stdio mode automatically and the web server does not launch. To re-authenticate, remove the tokens file and restart the server.

## MCP client configuration (example for Claude Desktop)

{ "mcpServers": { "spreadsheet_local": { "command": "node", "args": ["/absolute/path/to/spreadsheet_local_mcp_server/dist/index.js"], "env": { "GOOGLE_REDIRECT_URI": "http://localhost:8080/auth/callback" } } } }

Note: Replace `/absolute/path/to/...` with the actual absolute path to the deployed server. The Google redirect URI must match what you configured in Google Cloud Console.

Configuration notes

Authentication uses Google OAuth. The local server opens a browser to http://localhost:8080/auth/login to sign in with your Google account and grant access. If you already completed authentication in a previous session, the server will reuse the existing tokens unless you remove them to re-authenticate.

Available tools and how to use them

The server exposes the get_data tool, which retrieves data from a Google Spreadsheet URL or a Google Drive file URL. You can optionally specify a sheet name; if omitted, the first sheet is used.

Security and maintenance notes

Keep your OAuth credentials secure. Do not expose the client secret. If you need to revoke access, delete the token store (e.g., the .tokens.json file) and restart the server to re-authenticate.

Troubleshooting

If the client cannot reach the OAuth login page, ensure your redirect URI is correctly configured in Google Cloud Console and that your local dev server is accessible at http://localhost:8080. If you see token errors, remove the token store and re-authenticate.

Notes

This server reads data from Google Sheets API and Drive API and supports Excel files as well. The setup requires a Google Cloud project with OAuth credentials and enabled APIs, plus a local Node.js environment.

Available tools

get_data

Fetches data from a Google Spreadsheet URL or Google Drive file URL. Optionally specify a sheet name; if omitted, the first sheet is used.