# Google Sheets MCP Server

An MCP server that stores todos and stock data in a Google Sheet and exposes CRUD tools.

## Features

**Todo tools:**
- `todo_list`
- `todo_get`
- `todo_create`
- `todo_update`
- `todo_delete`

**Stock tools:**
- `stock_list`
- `stock_get`
- `stock_update`

## 1) Google setup

1. Create a Google Cloud project.
2. Enable the Google Sheets API.
3. Create a service account and download its JSON key.
4. Create a Google Sheet and copy its Spreadsheet ID from the URL.
5. Share the sheet with the service account email as Editor.

## 2) Local setup

```bash
npm install
cp .env.example .env
```

Then edit `.env` with your values.

## 3) Run

Development:

```bash
npm run dev
```

The server listens on `http://localhost:8080/mcp` by default.

Build and run:

```bash
npm run build
npm start
```

## 4) Cloud Run deployment

One command deployment:

```bash
npm run deploy:cloudrun -- --project PROJECT_ID --region REGION
```

The deploy script uses `.env` by default and will:

- Build the image with `cloudbuild.yaml`
- Deploy to Cloud Run
- Print the final MCP endpoint URL

You can also override the env file:

```bash
npm run deploy:cloudrun -- --project PROJECT_ID --env-file .env.production
```

Build and submit the container image:

```bash
gcloud builds submit --tag gcr.io/PROJECT_ID/firstmcp
```

Deploy to Cloud Run:

```bash
gcloud run deploy firstmcp \
  --image gcr.io/PROJECT_ID/firstmcp \
  --platform managed \
  --region REGION \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_SHEETS_SPREADSHEET_ID=your_spreadsheet_id,GOOGLE_SHEETS_TODO_SHEET_NAME=todos,GOOGLE_SERVICE_ACCOUNT_EMAIL=your-service-account@project.iam.gserviceaccount.com,GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n'
```

Cloud Run will inject the `PORT` environment variable automatically. The MCP HTTP endpoint will be available at `/mcp` on the service URL.

Files added for deployment:

- `cloudbuild.yaml`
- `scripts/deploy-cloud-run.sh`
- `.gcloudignore`

## 5) MCP client config example

For an HTTP-capable MCP client, point it at the deployed endpoint:

```json
{
  "mcpServers": {
    "google-sheets-todos": {
      "url": "https://YOUR_CLOUD_RUN_URL/mcp"
    }
  }
}
```

For local testing, use:

```json
{
  "mcpServers": {
    "google-sheets-todos": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

## 6) Sheet format

The server uses 5 columns in the target sheet:

- `id`
- `title`
- `completed`
- `createdAt`
- `updatedAt`

The header row is created automatically if missing.