# SheetsDB MCP Server

A Model Context Protocol (MCP) server that enables Claude to interact with Google Sheets through the SheetsDB API.

## Features

- **Smart Data Addition** - Automatically detects empty vs existing sheets
- **Header Management** - Uses SheetsDB's `/keys` endpoint for reliable header detection  
- **CRUD Operations** - Read, import, update, and delete sheet data
- **Simple & Reliable** - Just 6 focused tools, ~150 lines of code

## Tools Available

1. **`get_keys`** - Get column headers from sheet
2. **`smart_add_data`** - Intelligently add data (import_json for empty sheets, create for existing)
3. **`read_sheet`** - Read data from sheet
4. **`import_json`** - Import JSON data to empty sheets
5. **`update_row`** - Update specific rows
6. **`delete_rows`** - Delete rows by criteria

## Quick Start

### Prerequisites
- Node.js 18+
- SheetsDB account and API endpoint
- Claude Desktop or compatible MCP client

### Installation

1. **Clone this repository:**
   ```bash
   git clone https://github.com/yourusername/sheetsdb-mcp-server.git
   cd sheetsdb-mcp-server
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Test the server:**
   ```bash
   npm start
   ```

### Local Claude Desktop Setup

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sheetsdb": {
      "command": "node",
      "args": ["/path/to/your/sheetsdb-mcp-server/server.js"]
    }
  }
}
```

### Deploy with Smithery.ai

1. **Push to GitHub:**
   ```bash
   git add .
   git commit -m "Initial commit"
   git push origin main
   ```

2. **Deploy on Smithery.ai:**
   - Go to [Smithery.ai](https://smithery.ai)
   - Click "Deploy MCP with GitHub"
   - Select this repository
   - The `mcp-config.json` will be automatically detected

3. **Use in Claude:**
   - Get your Smithery deployment URL
   - Add to Claude Desktop config or use directly

## Usage Examples

### Adding Meal Data
```
User: "Add chicken dinner (340 calories, 25g protein) to my calorie tracker: https://sheetdb.io/api/v1/your-id"

Claude will:
1. Call get_keys to check headers
2. Call smart_add_data with proper mapping
3. Either create headers (first time) or add to existing sheet
```

### Reading Data
```
User: "Show me my last 5 meals"
Claude: [Uses read_sheet with limit=5]
```

### Updating Entries  
```
User: "Update yesterday's breakfast calories to 350"
Claude: [Uses update_row to find and modify the entry]
```

## Configuration

The server expects SheetsDB endpoints in this format:
```
https://sheetdb.io/api/v1/YOUR_SHEET_ID
```

No additional configuration required - just provide the endpoint when using tools.

## Security Notes

- Endpoints are validated to ensure they're legitimate SheetsDB URLs
- No API keys stored in the server (SheetsDB handles auth via URL)
- All requests go directly to SheetsDB's secure endpoints

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

- Create an issue for bugs or feature requests
- Check SheetsDB documentation for API-specific questions
- See MCP documentation for protocol details