Skip to content
Back to search

gogig-mcp-server

An MCP server built with FastMCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/charanntm--gogig-mcp-server/badge.svg)](/listings/charanntm--gogig-mcp-server)

HTML

<a href="/listings/charanntm--gogig-mcp-server"><img src="/api/listings/charanntm--gogig-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).

uv sync

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 193 lines
  1. # Gogig MCP Server
  2. An MCP server built with [FastMCP](https://gofastmcp.com).
  3. ## Setup
  4. Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
  5. ```bash
  6. uv sync
  7. ```
  8. ## Run
  9. ```bash
  10. uv run python -m app.main
  11. ```
  12. The server starts on `http://0.0.0.0:8100/mcp`.
  13. ## Configuration
  14. Settings are read from environment variables prefixed with `GOGIG_`, or a `.env` file:
  15. | Variable | Default | Description |
  16. | -------------------- | ----------------------- | ---------------------------------------- |
  17. | `GOGIG_HOST` | `0.0.0.0` | Bind host (http transport) |
  18. | `GOGIG_PORT` | `8000` | Bind port (http transport) |
  19. | `GOGIG_TRANSPORT` | `http` | `http` or `stdio` |
  20. | `GOGIG_API_BASE_URL` | `http://localhost:8080` | Base URL of the gogig-api-nestjs API |
  21. | `GOGIG_TOKEN` | (empty) | Fallback bearer token, for `stdio` |
  22. | `GOGIG_AUTH_ENABLED` | `false` | Turn on the OAuth login flow |
  23. | `GOGIG_AUTH_CLIENT_ID` | (empty) | The `AuthClient.clientId` to log in as |
  24. | `GOGIG_PUBLIC_URL` | `http://localhost:8000` | Externally visible URL of this server |
  25. | `GOGIG_AUTH_ORIGIN` | `http://localhost:8000` | `Origin` sent to gOGig; must be in `allowedUrls` |
  26. | `GOGIG_OAUTH_CLIENT_ID` | (empty) | A fixed OAuth client id, for clients configured by hand |
  27. | `GOGIG_OAUTH_REDIRECT_URIS` | claude.ai + Inspector callbacks | Allowlist for that client's `redirect_uri` |
  28. ## Authentication
  29. Every tool call reaches the API as the **end user**, so the API's guards decide
  30. what they may read. A call with no credential is refused. Three ways a caller
  31. proves who they are, most specific first:
  32. 1. **OAuth login** (`GOGIG_AUTH_ENABLED=true`) — the client is sent to a login
  33. page, the user signs in with a one-time code, and the client receives an
  34. access token and a refresh token. See below.
  35. 2. **Forwarded bearer** — the caller's own `Authorization` header, passed
  36. straight through. This is what MCP Inspector does.
  37. 3. **`GOGIG_TOKEN`** — for stdio clients, which have no request to read a
  38. header from. Accepted with or without the `Bearer ` prefix.
  39. Put `GOGIG_TOKEN` in `.env` (gitignored) or the MCP client's own `env` block —
  40. never in source.
  41. ## OAuth login
  42. FastMCP supplies the OAuth 2.1 protocol — discovery, PKCE, dynamic client
  43. registration, `/authorize`, `/token`, `/register` — and this server supplies
  44. the identity half: `/login` collects a phone number or email, gOGig sends a
  45. one-time code, and `/login/verify` exchanges it for a gOGig session.
  46. The access token a client holds is **ours**, not gOGig's. The gOGig token sits
  47. behind it in memory and is forwarded on each tool call, renewed through gOGig's
  48. `/renewAccessToken` when its 4-hour life runs out. Sessions are in memory, so
  49. restarting the server signs everyone out.
  50. ### One-time setup
  51. gOGig's login endpoints are client-gated, so this server needs an `AuthClient`
  52. row whose `allowedUrls` contains its origin. `secret_key` is the JWT signing
  53. secret for anonymous client tokens — generate a long random string:
  54. ```sql
  55. INSERT INTO AuthClient (clientId, name, secret_key, allowedUrls)
  56. VALUES ('mcp_gogig', 'gogig-mcp-server', '<long random secret>', 'http://localhost:8000');
  57. ```
  58. Then:
  59. ```bash
  60. GOGIG_AUTH_ENABLED=true
  61. GOGIG_AUTH_CLIENT_ID=mcp_gogig
  62. GOGIG_PUBLIC_URL=http://localhost:8000
  63. GOGIG_AUTH_ORIGIN=http://localhost:8000
  64. ```
  65. `GOGIG_PUBLIC_URL` is where clients reach this server — the OAuth metadata and
  66. the login page are advertised under it, so it must be externally visible.
  67. `GOGIG_AUTH_ORIGIN` is sent as the `Origin` header to gOGig and must appear in
  68. that row's `allowedUrls`, or every login is refused.
  69. Keep `mcp_gogig` out of `SINGLE_SESSION_CLIENT_IDS` unless you want signing in
  70. here to end the user's other sessions.
  71. ### Two different "client ids"
  72. Easy to conflate, and the error they produce looks the same:
  73. - **`GOGIG_AUTH_CLIENT_ID`** — the `AuthClient` row above. How *this server*
  74. authenticates to gOGig's login API.
  75. - **`GOGIG_OAUTH_CLIENT_ID`** — how an *MCP client* identifies itself to this
  76. server. Leave it blank and clients register themselves (DCR). Set it only
  77. when a client is configured with a client id by hand — note that registered
  78. clients are held in memory, so a restart turns a self-registered client away
  79. until it registers again, while a fixed one keeps working.
  80. They may hold the same string, but they are checked by different systems.
  81. ## Claude Desktop
  82. Add to `~/.config/Claude/claude_desktop_config.json`, keeping whatever keys are
  83. already there:
  84. ```json
  85. {
  86. "mcpServers": {
  87. "gogig-mcp-server": {
  88. "command": "/home/charan-t-m/.local/bin/uv",
  89. "args": [
  90. "--directory", "/home/charan-t-m/Devkernal/Gogig/gogig-mcp-server",
  91. "run", "python", "-m", "app.main"
  92. ],
  93. "env": {
  94. "GOGIG_TRANSPORT": "stdio",
  95. "GOGIG_API_BASE_URL": "http://localhost:8080",
  96. "GOGIG_TOKEN": "<your gOGig bearer token>"
  97. }
  98. }
  99. }
  100. }
  101. ```
  102. The API must be reachable at `GOGIG_API_BASE_URL`. Restart Claude Desktop
  103. fully after editing.
  104. ## Tools
  105. All tools are backed by the `mcp` module in
  106. [gogig-api-nestjs](../gogig-api-nestjs) (`src/modules/mcp/`), scoped through
  107. one `McpScopeService`: the whole team's work on campaigns the user leads,
  108. their own work everywhere else, every campaign for a gOGig admin. Every tool
  109. is a read except the two report tools below, which queue a real job and send
  110. a real email — see [Reports](#reports).
  111. ### Tasks
  112. - `get_task_summary(gig_id?, start_date?, end_date?)` — flagged / warned / clean counts and quality rates
  113. - `list_tasks(gig_id?, validation?, start_date?, end_date?, page?, page_size?)` — the user's tasks, newest first
  114. - `get_task_details(task_id)` — one task with its validation reasons and detector reads
  115. - `get_task_flag_reasons(gig_id?, start_date?, end_date?)` — why work is being flagged, busiest reason first
  116. ### Campaigns
  117. - `list_my_campaigns(page?, page_size?)` — the campaigns a `gig_id` may be set to
  118. - `get_campaign_performance(gig_id?, start_date?, end_date?, page?, page_size?)` — delivery and quality per campaign
  119. ### Users
  120. - `whoami(start_date?, end_date?)` — who the user is, how far they can see, and their own figures; worth calling first
  121. - `list_team_members(gig_id?, start_date?, end_date?, page?, page_size?)` — the roster under them, idle members included
  122. - `search_users(q, page?, page_size?)` — find a person by name; by email or phone too, for an admin
  123. - `get_user_performance(gig_id?, start_date?, end_date?, page?, page_size?)` — per-person figures, busiest first
  124. - `get_user_details(user_id?, start_date?, end_date?)` — one person's totals; omit `user_id` for the caller's own
  125. `list_team_members` is **membership**-derived (who is mapped under you, even
  126. with nothing submitted); `get_user_performance` is **work**-derived (whose
  127. submissions you are reading, including people with no mapping at all). They
  128. answer different questions and neither is a superset of the other.
  129. ### Reports
  130. The one WRITE surface. Generating a report queues a real cloud job and emails
  131. the result to the **caller's own account address** — never returned inline,
  132. never sent anywhere else. Scoped to the product's own rule: brand, agency, or
  133. admin; a plain executor is refused, same as the "Generate Report" button in
  134. the console.
  135. - `generate_campaign_report(gig_id, type, start_date?, end_date?, validation_reason?)` — `type` is `pdf` or `summary`; returns a `jobId` and a masked email address
  136. - `get_report_status(gig_id, type)` — progress and the download link once ready; `null` until the worker picks the job up
  137. To retry a failed job or refresh an expired download link, call
  138. `generate_campaign_report` again — a fresh job re-signs the link.
  139. ### Reading the numbers
  140. `flagged` is `taskValidation = 'error'` and `warned` is `'warn'`; severity is
  141. resolved per campaign by the validation pipeline. Rates divide by **validated**
  142. work only and are `null` until something has been validated — never 0.
  143. `delivery` is `submitted / totalTaskToBeDone`, `null` without a target, and may
  144. exceed 1. People are reported by name only — `emailId` and `phoneNumber` appear
  145. only on a gOGig admin's answer, where identifying a specific person is the
  146. point. Password, OTP and token columns are never read for anyone.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.