Skip to content

Commit 7306ac6

Browse files
timoschdtimoschd
committed
squashed minor Readme commits
1 parent 19e5cab commit 7306ac6

File tree

4 files changed

+106
-27
lines changed

4 files changed

+106
-27
lines changed

‎.github/workflows/README.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,26 @@ The `docker-publish.yml` workflow automatically builds and publishes Docker imag
1515
- Log in to Docker Hub
1616
- Go to Account Settings → Security → New Access Token
1717
- Name: `github-actions`
18-
- Permissions: Read, Write, Delete
18+
- Permissions: **Read & Write**
1919
- Copy the token (you won't see it again!)
2020

2121
3. **Configure GitHub Secrets**:
2222

2323
Go to your GitHub repository → Settings → Secrets and variables → Actions, and add:
2424

25-
| Secret Name | Description | Example Value |
26-
| -------------------- | ------------------------------ | ------------------ |
27-
| `DOCKERHUB_USERNAME` | Your Docker Hub username | `yourusername` |
28-
| `DOCKERHUB_TOKEN` | Docker Hub access token | `dckr_pat_xxx...` |
25+
| Secret Name | Description | Example Value |
26+
| ---------------------- | ---------------------------------------- | ------------------ |
27+
| `DOCKERHUB_USERNAME` | Your Docker Hub username | `yourusername` |
28+
| `DOCKERHUB_TOKEN` | Docker Hub access token (for image push) | `dckr_pat_xxx...` |
29+
| `DOCKERHUB_PASSWORD` | Your Docker Hub password (for README sync) | `your-password` |
30+
31+
**Note**: The README sync feature requires your actual Docker Hub **password**, not an access token.
32+
This is a limitation of the Docker Hub API. If you prefer not to store your password in GitHub Secrets,
33+
you can manually update the README on Docker Hub's website instead.
34+
35+
**Troubleshooting**: If you encounter a "409 Conflict" error, this is usually harmless and means the README
36+
is already up-to-date. The workflow will continue successfully even if this step fails (it won't block your
37+
image from being published). You can also manually update the README on Docker Hub if needed.
2938

3039
4. **Push to trigger build**:
3140
```bash
@@ -38,7 +47,7 @@ The `docker-publish.yml` workflow automatically builds and publishes Docker imag
3847
- ✅ **Automatic tagging** based on git tags and branches
3948
- ✅ **Pull request builds** (without pushing)
4049
- ✅ **Build caching** for faster builds
41-
- ✅ **README sync** to Docker Hub
50+
- ✅ **README sync** to Docker Hub (updates repository description automatically)
4251
- ✅ **Manual trigger** via workflow_dispatch
4352

4453
### Image Tags

‎.github/workflows/SECRETS.md‎

Lines changed: 22 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -10,31 +10,36 @@ Configure these in your GitHub repository: **Settings → Secrets and variables
1010

1111
Required for the `docker-publish.yml` workflow:
1212

13-
| Secret Name | Description | How to Get |
14-
| -------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
15-
| `DOCKERHUB_USERNAME` | Your Docker Hub username | Your Docker Hub account username |
16-
| `DOCKERHUB_TOKEN` | Docker Hub access token | Docker Hub → Account Settings → Security → New Access Token (with Read, Write, Delete permissions) |
13+
| Secret Name | Description | How to Get |
14+
| -------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
15+
| `DOCKERHUB_USERNAME` | Your Docker Hub username | Your Docker Hub account username |
16+
| `DOCKERHUB_TOKEN` | Docker Hub access token (for image push) | Docker Hub → Account Settings → Security → New Access Token (with Read & Write permissions) |
17+
| `DOCKERHUB_PASSWORD` | Your Docker Hub password (for README sync) | Your actual Docker Hub account password (required for README updates via API) |
18+
19+
**Note**: The README sync feature requires your actual password due to Docker Hub API limitations. If you prefer not to store your password, you can remove the "Update Docker Hub description" step from the workflow and manually update the README on Docker Hub's website.
1720

1821
### For Cloud Run Deployment (Workload Identity Federation - Recommended)
1922

20-
| Secret Name | Description | How to Get |
21-
| --------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
22-
| `GCP_PROJECT_ID` | Your GCP project ID | `gcloud config get-value project` |
23-
| `WIF_PROVIDER` | Workload Identity Federation provider resource name | Format: `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_NAME/providers/PROVIDER_NAME` |
24-
| `WIF_SERVICE_ACCOUNT` | Service account email for Workload Identity Federation | Format: `SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com` |
25-
| `BIGQUERY_PROJECT` | BigQuery project ID (can be same or different from GCP) | Your BigQuery project ID |
26-
| `BIGQUERY_LOCATION` | BigQuery location/region | e.g., `us-central1`, `europe-west4`, `asia-northeast1` |
23+
| Name | Type | Description | How to Get |
24+
| --------------------- | ---- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
25+
| `GCP_PROJECT_ID` | Variable | Your GCP project ID | `gcloud config get-value project` |
26+
| `WIF_PROVIDER` | Secret | Workload Identity Federation provider resource name | Format: `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_NAME/providers/PROVIDER_NAME` |
27+
| `WIF_SERVICE_ACCOUNT` | Secret | Service account email for Workload Identity Federation | Format: `SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com` |
28+
| `BIGQUERY_PROJECT` | Variable | BigQuery project ID (can be same or different from GCP) | Your BigQuery project ID |
29+
| `BIGQUERY_LOCATION` | Variable | BigQuery location/region | e.g., `us-central1`, `europe-west4`, `asia-northeast1` |
30+
31+
**Note**: Project IDs and locations are not sensitive and can be stored as **Variables** instead of **Secrets** for better visibility. Go to **Settings → Secrets and variables → Actions → Variables tab** to add them.
2732

2833
### For Service Account Key (Alternative)
2934

3035
If not using Workload Identity Federation, use these instead:
3136

32-
| Secret Name | Description | How to Get |
33-
| ------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
34-
| `GCP_PROJECT_ID` | Your GCP project ID | `gcloud config get-value project` |
35-
| `GCP_SA_KEY` | Service account JSON key (base64) | Create key, then: `cat key.json \| base64` |
36-
| `BIGQUERY_PROJECT` | BigQuery project ID | Your BigQuery project ID |
37-
| `BIGQUERY_LOCATION` | BigQuery location/region | e.g., `us-central1`, `europe-west4` |
37+
| Name | Type | Description | How to Get |
38+
| ------------------- | ---- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
39+
| `GCP_PROJECT_ID` | Variable | Your GCP project ID | `gcloud config get-value project` |
40+
| `GCP_SA_KEY` | Secret | Service account JSON key (base64) | Create key, then: `cat key.json \| base64` |
41+
| `BIGQUERY_PROJECT` | Variable | BigQuery project ID | Your BigQuery project ID |
42+
| `BIGQUERY_LOCATION` | Variable | BigQuery location/region | e.g., `us-central1`, `europe-west4` |
3843

3944
## Optional Secrets
4045

‎.github/workflows/docker-publish.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,10 +66,11 @@ jobs:
6666

6767
- name: Update Docker Hub description
6868
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
69+
continue-on-error: true
6970
uses: peter-evans/dockerhub-description@v4
7071
with:
7172
username: ${{ secrets.DOCKERHUB_USERNAME }}
72-
password: ${{ secrets.DOCKERHUB_TOKEN }}
73+
password: ${{ secrets.DOCKERHUB_PASSWORD }}
7374
repository: ${{ secrets.DOCKERHUB_USERNAME }}/${{ env.IMAGE_NAME }}
7475
short-description: ${{ github.event.repository.description }}
7576
readme-filepath: ./README.md

‎README.md‎

Lines changed: 67 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# BigQuery MCP server
22

3-
[![smithery badge](https://smithery.ai/badge/mcp-server-bigquery)](https://smithery.ai/server/mcp-server-bigquery)
3+
[![Build and Push to Docker Hub](https://github.com/timoschd/mcp-server-bigquery/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/timoschd/mcp-server-bigquery/actions/workflows/docker-publish.yml)
4+
[![Docker Hub](https://img.shields.io/docker/v/timoschd/mcp-server-bigquery?label=Docker%20Hub&logo=docker)](https://hub.docker.com/r/timoschd/mcp-server-bigquery)
45

56
A Model Context Protocol server that provides access to BigQuery. This server enables LLMs to inspect database schemas and execute queries.
67

@@ -12,8 +13,20 @@ A Model Context Protocol server that provides access to BigQuery. This server en
1213
- 🎯 Dataset filtering for security and performance
1314
- 🚀 Dual transport support (stdio for local, HTTP/SSE for cloud deployment)
1415

16+
## Deployment Options
17+
18+
This server can be deployed in multiple ways to suit different use cases:
19+
20+
- **📦 PyPI Package** - Install via `uvx` or `uv` for local use with Claude Desktop or other MCP clients
21+
- **🐳 Docker Hub** - Pre-built multi-architecture images available at [`timoschd/mcp-server-bigquery`](https://hub.docker.com/r/timoschd/mcp-server-bigquery)
22+
- **☁️ Google Cloud Run** - Deploy as a serverless HTTP/SSE endpoint with automatic scaling
23+
- **🔧 Local Development** - Use Podman Compose for containerized local development
24+
25+
All deployment methods support both **stdio** (for local MCP clients) and **HTTP/SSE** (for cloud/remote access) transports.
26+
1527
## Table of Contents
1628

29+
- [Deployment Options](#deployment-options)
1730
- [Components](#components)
1831
- [Configuration](#configuration)
1932
- [Quickstart](#quickstart)
@@ -119,7 +132,20 @@ On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
119132
}
120133
```
121134

122-
Replace `{{PATH_TO_REPO}}`, `{{GCP_PROJECT_ID}}`, and `{{GCP_LOCATION}}` with the appropriate values.
135+
##### Remote Server Configuration (SSE)
136+
137+
To connect to a remotely deployed server (e.g., on Cloud Run):
138+
139+
```json
140+
"mcpServers": {
141+
"bigquery": {
142+
"transport": "sse",
143+
"url": "https://your-server-url.run.app/messages"
144+
}
145+
}
146+
```
147+
148+
Replace `{{PATH_TO_REPO}}`, `{{GCP_PROJECT_ID}}`, `{{GCP_LOCATION}}`, and `https://your-server-url.run.app` with the appropriate values.
123149

124150
### Docker Deployment
125151

@@ -178,7 +204,7 @@ docker run -p 8080:8080 \
178204
timoschd/mcp-server-bigquery:latest
179205
```
180206

181-
#### Using Podman Compose
207+
#### Using Podman Compose/ Docker Compose
182208

183209
A `podman-compose.yml` file is provided for easy local development:
184210

@@ -189,6 +215,10 @@ cp .env.example .env
189215
# Start the service
190216
podman-compose up
191217
```
218+
OR
219+
```bash
220+
docker-compose up
221+
```
192222

193223
The compose file supports configurable environment variables:
194224
- `PORT`: External port mapping (default: 8085)
@@ -227,6 +257,8 @@ cp .github/workflows/deploy-cloud-run.yml.example .github/workflows/deploy-cloud
227257
git push origin main
228258
```
229259

260+
---
261+
230262
## Development
231263

232264
### Building and Publishing
@@ -318,6 +350,31 @@ The server supports two transport modes:
318350
- `POST /messages`: Send tool invocation requests
319351
- **Configuration**: Set `--transport http` or `MCP_TRANSPORT=http`
320352

353+
#### Connecting MCP Clients to Remote SSE Server
354+
355+
To connect an MCP client (like Claude Desktop or Windsurf) to a remotely deployed server using SSE transport:
356+
357+
**Configuration example** (e.g., in `mcp_config.json` or Claude Desktop config):
358+
359+
```json
360+
{
361+
"mcpServers": {
362+
"bigquery": {
363+
"disabled": false,
364+
"transport": "sse",
365+
"url": "https://your-server-url.run.app/messages"
366+
}
367+
}
368+
}
369+
```
370+
371+
Replace `https://your-server-url.run.app` with your actual deployment URL:
372+
- **Cloud Run**: `https://mcp-server-bigquery-xxxxx-uc.a.run.app`
373+
- **Custom domain**: `https://bigquery-mcp.yourdomain.com`
374+
- **Local testing**: `http://localhost:8080`
375+
376+
The `/messages` path is required for SSE communication.
377+
321378
## Authentication
322379

323380
The server supports multiple authentication methods:
@@ -334,6 +391,13 @@ The server supports multiple authentication methods:
334391
- Works with `gcloud auth application-default login`
335392
- Automatically available in Google Cloud environments (Cloud Run, GCE, etc.)
336393

394+
## Support
395+
396+
For questions, issues, or feedback:
397+
- 📧 Email: [[email protected]](mailto:[email protected])
398+
- 🐛 Issues: [GitHub Issues](https://github.com/timoschd/mcp-server-bigquery/issues)
399+
- 💬 Discussions: [GitHub Discussions](https://github.com/timoschd/mcp-server-bigquery/discussions)
400+
337401
## License
338402

339403
MIT

0 commit comments

Comments
 (0)