Skip to content
Back to search

flux-search

MarketplaceWorks with Claude CodeGitHub

MCP server for the Flux API: search, fetch, Lineage and account tools

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/flux-search--flux-mcp/badge.svg)](/listings/flux-search--flux-mcp)

HTML

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

Install

Install instructions from the README

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

Claude Code

/plugin marketplace add Flux-Search/flux-MCP
/plugin install flux@flux-search

This installs the tools and the skill. Claude Code asks for your Flux API key and keeps it in your system's credential store, not in a settings file. Start a new session afterwards. `/plugin` updates it later.

For the tools without the skill:

claude mcp add flux --env FLUX_API_KEY=user_sk_... -- npx -y github:Flux-Search/flux-MCP

Claude Desktop

Download `flux.mcpb` from the [latest release](https://github.com/Flux-Search/flux-MCP/releases/latest) and open it, or drag it onto Settings, Extensions. Claude Desktop asks for your Flux API key and runs the server itself, so Node.js is not needed.

Codex CLI and IDE

codex mcp add flux --env FLUX_API_KEY=user_sk_... -- npx -y github:Flux-Search/flux-MCP

To keep the key out of your shell history in Windows PowerShell:

$key = Read-Host "Flux API key"
codex mcp add flux --env "FLUX_API_KEY=$key" -- npx -y github:Flux-Search/flux-MCP
Remove-Variable key

The skill for Codex:

npx skills add https://github.com/Flux-Search/flux-MCP/tree/main/codex --skill flux-codex --agent codex --global

Check it with `codex mcp get flux`, or `/mcp` inside Codex. Codex lists the server as `Auth unsupported`, which is expected: the key is passed as an environment variable, not through OAuth. `--env` saves the key in Codex's local config, so do not commit or share that file.

Codex Cloud

Add this to the project's `.codex/config.toml`, and store `FLUX_API_KEY` as a Cloud environment secret. Never put the key itself in the file.

[mcp_servers.flux]
command = "npx"
args = ["-y", "github:Flux-Search/flux-MCP"]
env_vars = ["FLUX_API_KEY"]
tool_timeout_sec = 150
startup_timeout_sec = 30

Cursor and other MCP clients

Any client that starts a server with a command works the same way. For Cursor, add this under `mcpServers` in `~/.cursor/mcp.json`:

{
  "flux": {
    "command": "npx",
    "args": ["-y", "github:Flux-Search/flux-MCP"],
    "env": { "FLUX_API_KEY": "user_sk_..." }
  }
}

Updating

The Claude Code plugin updates through `/plugin`. Claude Desktop updates when you install a newer `flux.mcpb`. `npx -y github:Flux-Search/flux-MCP` fetches the latest version each time your client starts it; add a tag such as `#v0.4.0` to the end to pin one.

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.

.claude-plugin/marketplace.json · Manifest · 16 lines
  1. {
  2. "name": "flux-search",
  3. "owner": {
  4. "name": "Flux Search"
  5. },
  6. "metadata": {
  7. "description": "Flux for Claude Code: the search and lineage tools, and the skill that teaches when to use them."
  8. },
  9. "plugins": [
  10. {
  11. "name": "flux",
  12. "source": "./",
  13. "description": "Search the web and read documents with Flux: the passages that answer a question, with people, places, organisations and dates written in."
  14. }
  15. ]
  16. }
README.md · README · 202 lines
  1. # Flux MCP
  2. Flux for Claude, Codex, Cursor and any other MCP client. It gives your assistant four tools:
  3. - `search` searches the web and returns ranked results. Pages Flux reads come back with the passages that answer the query.
  4. - `lineage` reads a document or a web page and returns only the passages that answer your questions. People, places, organisations and dates are written into each passage where it needs them, such as the name behind "she" or the exact month behind "last April".
  5. - `fetch` returns one web page whole, as clean markdown with its title and published date.
  6. - `account` shows your balance. It is free.
  7. The Claude Code plugin also installs a skill that teaches Claude when to use each tool and how to report what comes back.
  8. ## What you need
  9. - A Flux API key. It starts with `user_sk_` (personal) or `org_sk_` (workspace). Create one at [app.fluxsearch.io/keys](https://app.fluxsearch.io/keys).
  10. - Node.js 18 or newer, for every client except Claude Desktop. Check with `node --version`, and install it from [nodejs.org](https://nodejs.org) if that fails.
  11. Nothing is cloned or built. Each install below is one step, and starting a new session loads it.
  12. ## Install
  13. ### Claude Code
  14. ```
  15. /plugin marketplace add Flux-Search/flux-MCP
  16. /plugin install flux@flux-search
  17. ```
  18. This installs the tools and the skill. Claude Code asks for your Flux API key and keeps it in your system's credential store, not in a settings file. Start a new session afterwards. `/plugin` updates it later.
  19. For the tools without the skill:
  20. ```bash
  21. claude mcp add flux --env FLUX_API_KEY=user_sk_... -- npx -y github:Flux-Search/flux-MCP
  22. ```
  23. ### Claude Desktop
  24. Download `flux.mcpb` from the [latest release](https://github.com/Flux-Search/flux-MCP/releases/latest) and open it, or drag it onto Settings, Extensions. Claude Desktop asks for your Flux API key and runs the server itself, so Node.js is not needed.
  25. ### Codex CLI and IDE
  26. ```bash
  27. codex mcp add flux --env FLUX_API_KEY=user_sk_... -- npx -y github:Flux-Search/flux-MCP
  28. ```
  29. To keep the key out of your shell history in Windows PowerShell:
  30. ```powershell
  31. $key = Read-Host "Flux API key"
  32. codex mcp add flux --env "FLUX_API_KEY=$key" -- npx -y github:Flux-Search/flux-MCP
  33. Remove-Variable key
  34. ```
  35. The skill for Codex:
  36. ```bash
  37. npx skills add https://github.com/Flux-Search/flux-MCP/tree/main/codex --skill flux-codex --agent codex --global
  38. ```
  39. Check it with `codex mcp get flux`, or `/mcp` inside Codex. Codex lists the server as `Auth unsupported`, which is expected: the key is passed as an environment variable, not through OAuth. `--env` saves the key in Codex's local config, so do not commit or share that file.
  40. ### Codex Cloud
  41. Add this to the project's `.codex/config.toml`, and store `FLUX_API_KEY` as a Cloud environment secret. Never put the key itself in the file.
  42. ```toml
  43. [mcp_servers.flux]
  44. command = "npx"
  45. args = ["-y", "github:Flux-Search/flux-MCP"]
  46. env_vars = ["FLUX_API_KEY"]
  47. tool_timeout_sec = 150
  48. startup_timeout_sec = 30
  49. ```
  50. ### Cursor and other MCP clients
  51. Any client that starts a server with a command works the same way. For Cursor, add this under `mcpServers` in `~/.cursor/mcp.json`:
  52. ```json
  53. {
  54. "flux": {
  55. "command": "npx",
  56. "args": ["-y", "github:Flux-Search/flux-MCP"],
  57. "env": { "FLUX_API_KEY": "user_sk_..." }
  58. }
  59. }
  60. ```
  61. ### Updating
  62. The Claude Code plugin updates through `/plugin`. Claude Desktop updates when you install a newer `flux.mcpb`. `npx -y github:Flux-Search/flux-MCP` fetches the latest version each time your client starts it; add a tag such as `#v0.4.0` to the end to pin one.
  63. ## Using it
  64. Ask in plain language:
  65. - "Search for the latest UK inflation figure and tell me where it comes from."
  66. - "Read https://example.com/article and tell me why prices rose."
  67. - "Use lineage on this report and list everyone it mentions", then paste the text.
  68. - "What's my Flux balance?"
  69. [examples/](examples/) has three short articles with prompts to try.
  70. ### `lineage`
  71. Send `text` or `url`, and your questions in `queries`.
  72. | Argument | |
  73. |---|---|
  74. | `text` | The document, up to 60,000 characters. |
  75. | `url` | A page for Flux to fetch and read. If the site refuses, you get an error and are not charged. |
  76. | `queries` | Up to 10 questions. Each is a full pass over the document and is billed as one. Leave it out to get every passage, which is longer than the input. |
  77. | `query` | One question. The same as `queries` with one entry. |
  78. | `published` | When a pasted text was published, as an ISO date. It lets "last April" resolve to the right year. |
  79. | `documents` | Up to 100 documents in one call, each with its own `text` or `url`, and optionally its own `queries` and `published`. Documents that cannot be read are listed and not charged. |
  80. ### `search`
  81. | Argument | |
  82. |---|---|
  83. | `query` | What to search for. Required. |
  84. | `max_results` | 1 to 20, default 10. |
  85. | `enrich` | How many results Flux reads for passages. The default is all of them. `0` returns results without reading any pages, which is fastest. |
  86. | `allowed_domains` | Only return pages from these sites, up to 10. |
  87. | `blocked_domains` | Never return pages from these sites, up to 20. |
  88. ### `fetch`
  89. | Argument | |
  90. |---|---|
  91. | `url` | A public http or https address. Required. |
  92. Pages longer than 100,000 characters are cut, with a note saying so.
  93. ### `account`
  94. No arguments. Returns your balance and roughly how many tokens of Lineage input it covers.
  95. ### What comes back
  96. Passages, each with a relevance score. The text is the passage with its context written in, ready to paste into another prompt:
  97. > She [Jane Doe] said the ministry raised fuel prices on Tuesday [Jul 28, 2026].
  98. Under each passage, what it mentions, such as `person: She -> Jane Doe`. An arrow means a vague mention was matched to a full name or a date.
  99. Search results also carry a direct answer when the index has one, related searches, and a note for any page Flux could not read.
  100. Every call ends with its cost in dollars.
  101. ## Pricing
  102. Lineage is billed by the tokens it reads, once per question: five questions over one document are five passes. Search and fetch are a flat price each. The account tool is free, and errors are never charged. Current prices are at [fluxsearch.io/pricing](https://fluxsearch.io/pricing).
  103. ## Good to know
  104. - Read any WARNING line. Lineage warns when only the start of a long document was read. Search warns when the index ran in a reduced mode.
  105. - A document can be up to 60,000 characters, about 9,000 words. Split longer ones, or use `documents`.
  106. - A `402` error means the balance is too low. Add credit at [app.fluxsearch.io](https://app.fluxsearch.io).
  107. ## Troubleshooting
  108. | What you see | What to do |
  109. |---|---|
  110. | The tools do not appear | Start a new session, then check `claude mcp list` or `codex mcp get flux`. |
  111. | `FLUX_API_KEY is not set` | The server started without a key. Register it again with `--env FLUX_API_KEY=...`, or add the Cloud secret. |
  112. | `Auth unsupported` in Codex | Expected. See the Codex section. |
  113. | `unauthorized` | The key is wrong or has been revoked. It starts with `user_sk_` or `org_sk_`. |
  114. | `insufficient_credits` | The balance is too low. Add credit and try again. |
  115. | `rate_limited` | Too many calls. Wait for the number of seconds in the message. |
  116. | `fetch_failed` | The site refused automated access or the page had no text. Nothing was charged. |
  117. | It times out | Try again, or raise `FLUX_TIMEOUT_MS`. |
  118. ## Settings
  119. | Variable | Default | |
  120. |---|---|---|
  121. | `FLUX_API_KEY` | none | Required. |
  122. | `FLUX_API_BASE_URL` | `https://fluxsearch.io` | Only set this to use a different deployment. |
  123. | `FLUX_TIMEOUT_MS` | `120000` | How long to wait for an answer, in milliseconds. |
  124. ## The API behind it
  125. The tools call the Flux REST API. To call it directly, see the [API reference](https://fluxsearch.io/api-reference) and the [getting started guide](https://fluxsearch.io/docs/getting-started). The API also has OpenAI-compatible endpoints, so the OpenAI SDK works with a changed base URL.
  126. ## Maintainers
  127. `bundle/index.js` is committed so that installing needs no toolchain, and CI fails if it does not match the source. The source is `src/index.ts` (the server) and `src/flux.ts` (request building, formatting and error text). After changing them, rebuild and commit the bundle:
  128. ```bash
  129. npm install
  130. npm test
  131. npm run bundle
  132. ```
  133. Bump the version in `package.json`, `src/index.ts`, `.claude-plugin/plugin.json` and `manifest.json` together. Pushing a `v*` tag runs the tests, builds `flux.mcpb` and attaches it to a GitHub release.
  134. `npm run build` only type-checks. The API is described by [fluxsearch.io/api-reference/openapi.json](https://fluxsearch.io/api-reference/openapi.json).
  135. ## License
  136. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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