Skip to content

Commit 5a89893

Browse files
aliwattersaliwatters
committed
Initial release: gsuite-mcp v0.1.0
Complete Google Workspace MCP server with 105+ tools: - Gmail (36 tools): search, read, send, reply, drafts, labels, filters, batch ops - Calendar (10 tools): events, recurring, free/busy, Google Meet - Docs (16 tools): create, edit, format, tables, images, headers/footers - Tasks (10 tools): lists, tasks, subtasks, due dates, reordering - Sheets (8 tools): read, write, append, batch, create - Contacts (12 tools): CRUD, search, groups - Drive (13 tools): search, download, upload, share, permissions Single Go binary. Multi-account support. MCP native.
0 parents  commit 5a89893

File tree

98 files changed

+21471
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

98 files changed

+21471
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Copilot Instructions for gsuite-mcp
2+
3+
## Project Overview
4+
5+
gsuite-mcp is a Go-based MCP (Model Context Protocol) server providing Gmail, Google Calendar, Google Docs, Google Tasks, Google Sheets, and Google Contacts operations with true multi-account support. It's designed as a single binary alternative to Python-based Google Workspace integrations.
6+
7+
**Key differentiators:**
8+
- Per-operation account selection via `account` parameter
9+
- JSON Schema draft 2020-12 (not draft-07)
10+
- Single Go binary, no runtime dependencies
11+
- Full inbox management (archive, trash, labels, batch operations)
12+
13+
## Technology Stack
14+
15+
| Component | Technology |
16+
|-----------|------------|
17+
| Language | Go 1.23+ |
18+
| MCP Framework | [mcp-go](https://github.com/mark3labs/mcp-go) by mark3labs |
19+
| Auth | OAuth2 via `golang.org/x/oauth2` with Google provider |
20+
| APIs | Gmail, Calendar, Docs, Tasks, Sheets, People (Contacts) |
21+
22+
## Project Layout
23+
24+
```
25+
gsuite-mcp/
26+
├── main.go # Entry point, CLI commands, tool registration
27+
├── CLAUDE.md # Claude Code entry point (pointers only)
28+
├── internal/
29+
│ ├── auth/ # OAuth2 authentication and token management
30+
│ ├── common/ # Shared helpers, constants, types
31+
│ ├── config/ # Configuration loading and account management
32+
│ ├── calendar/ # Google Calendar tools
33+
│ ├── contacts/ # Google Contacts tools
34+
│ ├── docs/ # Google Docs tools
35+
│ ├── drive/ # Google Drive tools
36+
│ ├── gmail/ # Gmail tools
37+
│ ├── sheets/ # Google Sheets tools
38+
│ └── tasks/ # Google Tasks tools
39+
├── docs/
40+
│ ├── AGENTS.md # AI agent development guidelines
41+
│ └── ROADMAP.md # Development phases
42+
├── README.md # User documentation
43+
└── INSTALLATION.md # Getting started guide
44+
```
45+
46+
## Build and Test Commands
47+
48+
```bash
49+
# Build the binary
50+
go build -o gsuite-mcp
51+
52+
# Run tests
53+
go test ./...
54+
55+
# Check for issues
56+
go vet ./...
57+
58+
# Format code
59+
gofmt -w .
60+
61+
# CLI commands (after building)
62+
./gsuite-mcp --help
63+
./gsuite-mcp init # Create default config
64+
./gsuite-mcp auth <label> # Authenticate an account
65+
./gsuite-mcp accounts # List configured accounts
66+
```
67+
68+
## Configuration Locations
69+
70+
```
71+
~/.config/gsuite-mcp/
72+
├── config.json # Account configuration
73+
├── credentials/
74+
│ └── {label}.json # OAuth tokens per account
75+
└── client_secret.json # Google OAuth app credentials
76+
```
77+
78+
## Code Patterns
79+
80+
### Account Resolution
81+
82+
All tools accept an optional `account` parameter. Resolution order:
83+
1. If provided: match by label first, then by email
84+
2. If omitted: use `default_account` from config
85+
3. If no default and single account: use that account
86+
4. Otherwise: return error
87+
88+
### Tool Registration
89+
90+
Use the mcp-go fluent API. Always include the account parameter:
91+
92+
```go
93+
s.AddTool(mcp.NewTool("gmail_tool_name",
94+
mcp.WithDescription("Tool description"),
95+
mcp.WithString("required_param", mcp.Required(), mcp.Description("...")),
96+
mcp.WithString("account", mcp.Description("Account label or email (uses default if omitted)")),
97+
), handlerFunction)
98+
```
99+
100+
### Error Handling
101+
102+
Return user-friendly errors via MCP:
103+
104+
```go
105+
// For expected errors
106+
return mcp.NewToolResultError("Clear error message"), nil
107+
108+
// For successful results
109+
return mcp.NewToolResultText("Success message or JSON"), nil
110+
111+
// Only return Go errors for unexpected failures
112+
return nil, fmt.Errorf("unexpected error: %w", err)
113+
```
114+
115+
### Gmail API Calls
116+
117+
```go
118+
import (
119+
"google.golang.org/api/gmail/v1"
120+
"google.golang.org/api/option"
121+
)
122+
123+
client, err := authManager.GetClient(ctx, account)
124+
if err != nil {
125+
return mcp.NewToolResultError(fmt.Sprintf("Authentication error: %v", err)), nil
126+
}
127+
128+
srv, err := gmail.NewService(ctx, option.WithHTTPClient(client))
129+
if err != nil {
130+
return mcp.NewToolResultError(fmt.Sprintf("Failed to create Gmail service: %v", err)), nil
131+
}
132+
```
133+
134+
## Common Mistakes to Avoid
135+
136+
1. **Don't break multi-account support** - All tools must accept the `account` parameter
137+
2. **Don't use JSON Schema draft-07** - This project uses draft 2020-12
138+
3. **Don't commit credentials** - Never include tokens, emails, or client secrets
139+
4. **Don't add unnecessary dependencies** - Keep the binary lean
140+
5. **Don't return Go errors for user errors** - Use `mcp.NewToolResultError()` instead
141+
142+
## Commit Message Format
143+
144+
Use conventional commits:
145+
```
146+
feat(gmail): add gmail_send tool
147+
fix(auth): handle token refresh edge case
148+
docs: update README with new tool
149+
refactor(config): simplify account resolution
150+
test(config): add tests for edge cases
151+
```
152+
153+
## References
154+
155+
- [docs/AGENTS.md](../docs/AGENTS.md) - Full AI agent development guidelines
156+
- [docs/ROADMAP.md](../docs/ROADMAP.md) - Development phases and priorities
157+
- [Gmail API Documentation](https://developers.google.com/gmail/api/reference/rest)
158+
- [mcp-go Framework](https://github.com/mark3labs/mcp-go)
159+
- [MCP Specification](https://modelcontextprotocol.io/)

‎.github/workflows/release.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
release:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
with:
17+
fetch-depth: 0
18+
19+
- uses: actions/setup-go@v5
20+
with:
21+
go-version-file: go.mod
22+
23+
- name: Run GoReleaser
24+
uses: goreleaser/goreleaser-action@v6
25+
with:
26+
version: "~> v2"
27+
args: release --clean
28+
env:
29+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/test.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Test
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- uses: actions/setup-go@v5
16+
with:
17+
go-version-file: go.mod
18+
19+
- name: Build
20+
run: go build ./...
21+
22+
- name: Vet
23+
run: go vet ./...
24+
25+
- name: Test
26+
run: go test ./...
27+
28+
- name: Format check
29+
run: |
30+
if [ -n "$(gofmt -l .)" ]; then
31+
echo "Files not formatted:"
32+
gofmt -l .
33+
exit 1
34+
fi

‎.gitignore‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Binaries
2+
/gsuite-mcp
3+
*.exe
4+
dist/
5+
6+
# IDE
7+
.idea/
8+
.vscode/
9+
*.swp
10+
*.swo
11+
*~
12+
13+
# OS
14+
.DS_Store
15+
16+
# Test/debug
17+
*.log
18+
tmp/
19+
20+
# MCP/Claude Code activity files
21+
.mcp-activity.json
22+
.workflow-state.*
23+
.workflow-reports/
24+
.ax/
25+
rod-mcp.yaml
26+
27+
# Credentials (never commit)
28+
*.json
29+
!schemas/*.json
30+
credentials/
31+
.workflow-state.json

‎.goreleaser.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
version: 2
2+
3+
builds:
4+
- main: ./cmd/gsuite-mcp
5+
binary: gsuite-mcp
6+
env:
7+
- CGO_ENABLED=0
8+
goos:
9+
- linux
10+
- darwin
11+
- windows
12+
goarch:
13+
- amd64
14+
- arm64
15+
ldflags:
16+
- -s -w
17+
18+
archives:
19+
- formats: [tar.gz]
20+
name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
21+
format_overrides:
22+
- goos: windows
23+
formats: [zip]
24+
25+
checksum:
26+
name_template: "checksums.txt"
27+
28+
changelog:
29+
use: github-native
30+
31+
release:
32+
github:
33+
owner: aliwatters
34+
name: gsuite-mcp

‎CHANGELOG.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.0] - 2026-02-09
9+
10+
### Added
11+
12+
- **Gmail** (36 tools): Search, read, send, reply, archive, trash, labels, filters, drafts, threads, batch operations, vacation responder
13+
- **Calendar** (10 tools): List events, create/update/delete, recurring events, free/busy queries, Google Meet integration
14+
- **Docs** (16 tools): Create, read, append, insert, replace, delete, formatting, lists, tables, images, headers/footers
15+
- **Tasks** (10 tools): Lists, tasks, subtasks, due dates, completion, reordering
16+
- **Sheets** (8 tools): Read, write, append, batch operations, create, clear
17+
- **Contacts** (12 tools): List, search, create, update, delete, contact groups
18+
- **Drive** (13 tools): Search, get, download, upload, list, create folder, move, copy, trash, delete, share, permissions
19+
- Multi-account support with per-operation `account` parameter
20+
- Dynamic OAuth2 credential discovery
21+
- CLI subcommands: `init`, `auth`, `accounts`

‎CLAUDE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Claude Code Guidelines for gsuite-mcp
2+
3+
See **[docs/AGENTS.md](docs/AGENTS.md)** for full development guidelines, architecture, and patterns.
4+
5+
## Commands
6+
7+
| Command | Description |
8+
|---------|-------------|
9+
| `go build -o gsuite-mcp` | Build the binary |
10+
| `go test ./...` | Run all tests |
11+
| `go vet ./...` | Check for issues |
12+
| `gofmt -w .` | Format code |
13+
14+
## Documentation
15+
16+
- [docs/AGENTS.md](docs/AGENTS.md) — Development guidelines and patterns
17+
- [docs/ROADMAP.md](docs/ROADMAP.md) — Development phases and planning
18+
- [README.md](README.md) — User documentation and tool reference

0 commit comments

Comments
 (0)