Skip to content
Back to search

geniuslink-mcp-server

Build a TypeScript MCP server that authenticates with Geniuslink and exposes its supported link and analytics functions.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/loperkin--geniuslink-mcp-server"><img src="/api/listings/loperkin--geniuslink-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 Node.js 20+ and a local MCP client supporting stdio.

git clone https://github.com/loperkin/geniuslink-mcp-server.git
cd geniuslink-mcp-server
npm install
npm run build
npm start

`npm start` runs an MCP server over **stdio**, not a web dashboard. Use an MCP client to interact with its tools.

Set `GENIUSLINK_API_KEY` and `GENIUSLINK_API_SECRET` in your MCP client's private environment configuration. See [`.env.example`](.env.example). Never paste actual credentials into ChatGPT, screenshots, issues, or GitHub files.

The client uses the documented `X-Api-Key` and `X-Api-Secret` HTTP headers. The remote Worker has been used with a live account; local stdio setup must be configured and verified independently.

Sample stdio client configuration

Substitute your absolute installation path and provide credentials using your MCP client's secure secret mechanism. This is an illustrative configuration, not a ChatGPT remote connector configuration.

{
  "mcpServers": {
    "geniuslink": {
      "command": "node",
      "args": ["/absolute/path/to/geniuslink-mcp-server/dist/server.js"],
      "env": {
        "GENIUSLINK_API_KEY": "SET_PRIVATELY",
        "GENIUSLINK_API_SECRET": "SET_PRIVATELY"
      }
    }
  }
}

Do **not** save a real-key version of that JSON in a repository.

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 · 196 lines
  1. # Geniuslink MCP Server
  2. Community-built **read-only Geniuslink integration** for MCP clients, developed for Purpose in Practice and PIP Builds.
  3. > **Status (November 2026):** The production Cloudflare Workers remote MCP has been deployed, authenticated with GitHub OAuth, and used successfully for read-only Geniuslink link inventory and click reporting. The **local stdio implementation** below is a separate interface and some of its older documentation still describes pre-deployment testing. Geniuslink v1 is a legacy API; specific endpoints and metric availability can change.
  4. ## Start here: remote MCP vs. local stdio
  5. - **Production remote MCP:** `https://geniuslink-mcp-server.purposeinpractice5.workers.dev/mcp`, OAuth through GitHub. **Owner-only:** the current authorization code accepts only the `loperkin` GitHub identity; other users cannot connect their own Geniuslink accounts through this deployment.
  6. - **Staging remote MCP:** `https://geniuslink-mcp-oauth-test.purposeinpractice5.workers.dev/mcp`; intended for testing, not customer use.
  7. - **Local stdio MCP:** install and run from source with your own Geniuslink API credentials. Its tool set is not identical to the remote implementation.
  8. - **Agent usage guide:** [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) explains when to call each remote tool, pagination, analytics semantics, error handling, and safety.
  9. - **Security:** no Geniuslink secrets should be put in a chat, public skill, or repository. The remote endpoint is read-only and is **not** a general-purpose public API for other users.
  10. ### Remote production tools
  11. | Tool | Purpose |
  12. |---|---|
  13. | `geniuslink_api_status` | Verify server credential configuration without querying Geniuslink |
  14. | `geniuslink_list_links` | Search and paginate short links; inspect link-list click totals |
  15. | `geniuslink_link_click_trend` | Trend report for one short code |
  16. | `geniuslink_account_click_trend` | Account-wide click trend |
  17. | `geniuslink_link_clicks_by_country` | Country breakdown for a link |
  18. | `geniuslink_account_clicks_by_country` | Country breakdown for the account |
  19. | `geniuslink_groups` | List groups |
  20. The following **local stdio** tools are not exposed by the remote Worker: `geniuslink_list_all_links`, `geniuslink_link_top_attributes`, and `geniuslink_read_report`. The local and remote schemas may differ. Refer to `worker.js` for the remote implementation.
  21. ### Reading click metrics correctly
  22. - Link-list `totalClicks` is not necessarily a verified lifetime count; do not label it lifetime without confirmation of its reporting period.
  23. - `clicks` (raw), `clicksMinusBot` (excluding bots), `clicksMinusSharedAndBot`, and `spider` are distinct fields; report the metric used.
  24. - Clicks are not verified sales, conversions, or affiliate commissions.
  25. - Account and per-link date reports can return fewer date buckets than requested; state coverage and don't invent zeroes.
  26. - Shared short links cannot independently attribute traffic to YouTube versus GitHub versus the website.
  27. ## Local stdio implementation (separate from the remote Worker)
  28. ## Available local stdio MCP tools
  29. | Tool | API route | Purpose |
  30. |---|---|---|
  31. | `geniuslink_api_status` | None | Check local credential configuration safely |
  32. | `geniuslink_list_links` | `GET /v1/links/list` | Typed filtering, pagination and link click totals |
  33. | `geniuslink_list_all_links` | `GET /v1/links/list` | Fetch bounded consecutive pages with continuation offset |
  34. | `geniuslink_link_click_trend` | `GET /v1/reports/link-click-trend-by-resolution` | Link click trends |
  35. | `geniuslink_link_clicks_by_country` | `GET /v1/reports/link-clicks-by-country` | Link geography |
  36. | `geniuslink_link_top_attributes` | `GET /v1/reports/link-top-attributetype-for-range` | Link attribute breakdowns |
  37. | `geniuslink_account_click_trend` | `GET /v1/reports/click-trend-by-resolution` | Account click trends |
  38. | `geniuslink_account_clicks_by_country` | `GET /v1/reports/clicks-by-country` | Account geography |
  39. | `geniuslink_read_report` | Exact allowlisted GET path | Advanced access to documented endpoints |
  40. Other v1 GET endpoints visible in the API Explorer are included in the allowlist, including `/v1/affiliate/stats`, `/v1/conversion-tracking`, `/v1/exportdata` and group reporting. **Names alone do not establish which metrics or commission data these endpoints return.**
  41. No POST, PUT, PATCH or DELETE operations are exposed. **We do not assume Amazon affiliate commission data is available.**
  42. ## Verified from the v1 link-list Swagger schema
  43. The API Explorer confirms these optional query parameters for `GET /v1/links/list`:
  44. | Parameter | Type | Meaning |
  45. |---|---|---|
  46. | `baseShortCodes` | array of strings | Filter short codes; multi-value encoding still needs verification |
  47. | `linkTypes` | array of strings | Filter link types; valid values still need verification |
  48. | `sortBy` | string | Sort expression; valid values still need verification |
  49. | `take` | integer | Number of links requested |
  50. | `skip` | integer | Pagination offset |
  51. | `groupid` | integer | Group identifier; Swagger says 0 for all |
  52. | `keyword` | string | Keyword filter |
  53. | `includeArchived` | boolean | Include archived links |
  54. | `linksCreatedStart` | date-time | Created-date start |
  55. | `linksCreatedEnd` | date-time | Created-date end |
  56. The documented response has a `results` array, with fields including `shortUrlCode`, `domain`, `destinationUrl`, `productUrl`, `group`, `trackingCode`, `advertiser`, `totalClicks`, `previousPeriodTotalClicks`, and `percentChangePeriodOverPeriod`. It also includes `allLinksLoaded` and `errorMessage`, whose runtime semantics have not yet been verified.
  57. Example MCP arguments for `geniuslink_list_links`:
  58. ```json
  59. {"take":25,"skip":0,"groupid":0,"includeArchived":false}
  60. ```
  61. Example MCP arguments for `geniuslink_list_all_links`:
  62. ```json
  63. {"take":50,"skip":0,"maxPages":3}
  64. ```
  65. The pagination tool stops after a short page or the configured page limit and returns a `nextSkip` value. A full final page does **not** prove there are more links. To avoid inventing behavior, array filters currently accept at most one value, until their Swagger query serialization is verified.
  66. **Important:** `totalClicks` is a click count, not a verified conversion or commission figure. Its reporting period is not specified by the example schema, so do not label it lifetime or monthly without confirmation.
  67. ## Verified link click-trend parameters
  68. The API Explorer's `GET /v1/reports/link-click-trend-by-resolution` operation documents:
  69. - `shortcode` (required): link short code (not a full URL)
  70. - `start`, `end` (required): `YYYY-MM-DD`
  71. - `retailerid` (optional): retailer filter, e.g. `AMAZON`; omit for all
  72. - `resolution`: `hour`, `day`, `month` or `lifetime`
  73. - `dopreviousperiod`: integer flag, 0 or 1, for previous-period comparison
  74. Example MCP tool arguments:
  75. ```json
  76. {
  77. "shortcode": "eS1fw",
  78. "start": "2026-11-01",
  79. "end": "2026-11-18",
  80. "resolution": "day",
  81. "dopreviousperiod": 1
  82. }
  83. ```
  84. The documented response contains `clicksByDate` and `clicksByDatePP`, with timestamped `Key` and metric-bearing `Value` objects. Metrics include `clicks`, `clicksMinusBot`, `clicksMinusSharedAndBot`, `clientAffiliated`, `spider`, and potential consolidated commission/conversion fields. **The existence of these fields in the schema does not mean your account receives populated commission data.** We preserve the original response rather than treating example zeros as real performance.
  85. The remote production link and account trend tools have been used successfully; the local stdio interface and every optional v1 endpoint have not all been independently verified. In the copied Swagger parameter text, `shortcode` appears as a query parameter; confirm its placement in the expanded explorer if the live API rejects it.
  86. ## Install locally
  87. Requires Node.js 20+ and a local MCP client supporting stdio.
  88. ```bash
  89. git clone https://github.com/loperkin/geniuslink-mcp-server.git
  90. cd geniuslink-mcp-server
  91. npm install
  92. npm run build
  93. npm start
  94. ```
  95. `npm start` runs an MCP server over **stdio**, not a web dashboard. Use an MCP client to interact with its tools.
  96. Set `GENIUSLINK_API_KEY` and `GENIUSLINK_API_SECRET` in your MCP client's private environment configuration. See [`.env.example`](.env.example). Never paste actual credentials into ChatGPT, screenshots, issues, or GitHub files.
  97. The client uses the documented `X-Api-Key` and `X-Api-Secret` HTTP headers. The remote Worker has been used with a live account; local stdio setup must be configured and verified independently.
  98. ### Sample stdio client configuration
  99. Substitute your absolute installation path and provide credentials using your MCP client's secure secret mechanism. This is an illustrative configuration, not a ChatGPT remote connector configuration.
  100. ```json
  101. {
  102. "mcpServers": {
  103. "geniuslink": {
  104. "command": "node",
  105. "args": ["/absolute/path/to/geniuslink-mcp-server/dist/server.js"],
  106. "env": {
  107. "GENIUSLINK_API_KEY": "SET_PRIVATELY",
  108. "GENIUSLINK_API_SECRET": "SET_PRIVATELY"
  109. }
  110. }
  111. }
  112. }
  113. ```
  114. Do **not** save a real-key version of that JSON in a repository.
  115. ## Query parameters: verify before use
  116. For the **local stdio implementation**, some less-common report endpoints may still require consulting the Geniuslink API Explorer for documented parameter definitions. The remote Worker instead exposes typed parameters for its seven tools. Before calling a report, expand that specific operation in [the Geniuslink API Explorer](https://api.geni.us/) and read its parameter names, required fields and response examples.
  117. For example, the MCP call for `geniuslink_link_click_trend` has the form:
  118. ```json
  119. {"query":{"REPLACE_WITH_DOCUMENTED_PARAMETER":"REPLACE_WITH_VALUE"}}
  120. ```
  121. This is deliberately **not** a working API example; we won't guess parameter names or date formats.
  122. ## Safety and compatibility
  123. - Outbound requests are GET-only, sent to `https://api.geni.us` with redirects disabled.
  124. - Built-in endpoints are exact, fixed paths. Additional GET paths can be explicitly allowlisted with `GENIUSLINK_ALLOWED_GET_PATHS`.
  125. - No arbitrary hosts, arbitrary methods or credentials in query strings.
  126. - Requests time out after 15 seconds; responses are limited to 1 MiB.
  127. - API errors return HTTP status only, without logging response bodies that may contain sensitive information.
  128. - The **local server** uses stdio; the separately deployed Cloudflare Worker provides an authenticated HTTPS MCP endpoint restricted to the owner's GitHub account.
  129. - v1 is legacy. Do not assume it remains supported merely because its routes appear in Swagger.
  130. - No pricing information should be published in Purpose in Practice buying guides; let readers choose what fits their budgets.
  131. ## Development roadmap
  132. 1. Keep remote tool schemas and documentation aligned, with mocked tests for paging and reporting edge cases.
  133. 2. Validate the reporting period and semantics of `totalClicks` and verify date-bucket coverage.
  134. 3. Confirm which additional v1 or supported v3 reporting endpoints are reliable, including any actual conversion data.
  135. 4. If offering third-party access, design per-user Geniuslink authentication and isolation rather than sharing the owner's credentials.
  136. 5. Consider an optional agent skill after confirming that purchasers can actually connect to the required tools.
  137. ## References
  138. - [Geniuslink API Explorer](https://api.geni.us/)
  139. - [Geniuslink API documentation](https://intercom.geni.us/en/articles/1065234-geniuslink-api)
  140. - [Model Context Protocol](https://modelcontextprotocol.io/)
  141. ## License
  142. MIT. Independent community project; not affiliated with Geniuslink.

Ratings and comments

Sign in to rate this skill.

Sign in

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