FlashData MCP server

FlashData MCP

Release artifacts for 0.3.0 are available from GitHub Releases. npm availability is independent; check the registry before upgrading.

简体中文 · FlashData · API documentation · Pricing

Use Google Search, YouTube data, and downloads to your cloud storage from a terminal, Agent, or MCP client. This MIT-licensed package implements the tools and calls the FlashData REST APIs directly. It does not proxy a hosted MCP connection.

Source code is available at flashdatadev/flashdata-mcp. The npm package @flashdata-dev/mcp provides two commands: flashdata for single-call JSON output and flashdata-mcp for persistent stdio MCP.

To connect without running this local package, use the separate FlashData hosted MCP service. Its Official MCP Registry manifest and publishing instructions are maintained in this repository. The combined registration describes the hosted endpoint. The Registry also has separate manifests for 15 local task servers; each references a source-restricted MCPB bundle. Neither path publishes to npm.

For independent Registry entries and task-specific examples, use the 15-capability MCP guide index: Google Search, News, Images, Shopping, video search and Places; YouTube search, extended search, metadata, transcripts, uploader captions, license labels, channels, autocomplete and delivery to customer storage. Each guide includes request JSON, selected output fields, limits, costs and the corresponding FlashData documentation.

For a local server focused on one capability, see the 15 independent Smithery task servers. Each MCPB bundle has one data tool plus pricing, job and result reads restricted to that source. Installation is free; FlashData data calls use paid Credits.

This directory is a complete, standalone project. Use its contents as the root of your GitHub repository, including .github/ and .gitignore. Installation and tests require no files from another checkout.

Transcript and captions support one language or a list of 1–10 codes. Omit the language to prefer en-orig, then en. Lists preserve available tracks and per-language errors. See subtitle languages.

Choose a workflow

You want to	Start here
Connect an agent without a local server	Hosted MCP setup
Run the local stdio MCP server	Run locally
Install portable agent instructions	FlashData Skills
Use the standalone CLI for query, bulk and recovery workflows	FlashData CLI
Install a client plugin or a single-source integration	Task packages and the client sections below

This is the official MCP source repository. The separate flashdata-cli repository provides the standalone Go CLI; this npm package's flashdata executable is the original JSON tool client described below. Choose the installation matching your workflow because both command-line packages expose a command named flashdata.

Portable Skills are maintained in flashdata-skills. The copies here keep existing client plugins compatible. Existing Registry manifests, release downloads and independent integration repositories retain their published identifiers and artifact locations; see repository provenance.

Choose a task package

Python users can build the 15 independent Python / uvx CLIs. Their PyPI publication is still pending; the source includes local wheel installation instructions.

Homebrew users can install 15 independent task formulae from this repository as a third-party tap. Each formula builds the corresponding Python CLI from a checked GitHub release, with its own command and complete runtime dependencies.

For one capability, choose one of the 15 task packages. Each has one executable, one data source and its own examples, input schema and documentation. It runs as a JSON CLI or as a stdio MCP server using the mcp subcommand. For example:

npx --yes @flashdata-dev/google-news@0.1.0 --help
npx --yes @flashdata-dev/google-news@0.1.0 tools
npx --yes @flashdata-dev/google-news@0.1.0 call get_pricing

The last two commands require your API key in FLASHDATA_API_KEY and make only free reads. Task packages expose three CLI tools (the selected source, get_pricing, get_job) or four MCP tools (also get_result). They reject other sources and cross-source job reads, even with a broadly authorized key. The combined package below remains available for workflows that need several capabilities. Installation is free; FlashData API queries are paid.

Agent Skill

The FlashData Skill helps an agent use an existing FlashData MCP connection for source-backed web and video research. It includes recipes for video research, comparing search snapshots, and preparing knowledge-base records.

Install the Skill into your project with the skills CLI:

npx skills add flashdatadev/flashdata-skills --skill flashdata-mcp

Select your agent when prompted, or add --agent codex (or another supported agent). The default scope is the current project; use --global only if you want a user-wide installation. Review the Skill before installation.

This installs instructions and references, not the MCP executable or an account connection. Connect FlashData separately using the hosted setup or the local instructions below. The Skill contains no API keys and submits no queries during installation. Queries made through MCP use your existing FlashData Credits; account reads can verify a connection for free.

Example requests:

• “Use FlashData to estimate the cost of one web search without running it.”
• “Find three relevant YouTube videos, compare their available transcripts, and cite timestamps. Keep the work within my approved query budget.”
• “Compare this search snapshot with the previous one and prepare source-linked records for my knowledge base.”

The skills.sh directory uses aggregated installation telemetry for discovery; a successful installation is separate from directory ranking or security-audit approval. This Skill is MIT-licensed under this repository's license. The Skill does not require the local npm package.

Task-specific Skills

Choose a Skill for the capability you need. Each includes example requests, a terminal quick start, MCP usage, parameters and practical ways to use the results. The general flashdata-mcp research Skill remains available.

Capability	Skill	Examples
Google Search	google-search	Web research, site searches, PDF discovery and localized SERPs.
Google News	google-news	Topic coverage, company news and linked news briefings.
Google Image Search	google-image-search	Image references, diagrams and filtering by returned dimensions.
Google Shopping	google-shopping	Product discovery and comparing listed merchant offers.
Google Video Search	google-video-search	Tutorials, demonstrations and video discovery across websites.
Google Places Search	google-places	Local business lists with addresses and available ratings.
YouTube Search	youtube-search	Video discovery using date, duration, subtitle and sorting filters.
YouTube Extended Search	youtube-extended-search	Larger video datasets and creator discovery, up to 700 requested results.
YouTube Video Metadata	youtube-metadata	Video details, statistics, chapters and format inspection.
YouTube Transcripts	youtube-transcript	Video summaries, timestamped quotes and transcript exports.
YouTube Captions	youtube-captions	Uploader captions and local SRT/WebVTT conversion.
YouTube Channel Data	youtube-channel	Channel profiles, recent uploads and video CSV exports.
YouTube Autocomplete	youtube-autocomplete	Keyword ideas and suggestions by language and region.
YouTube License Check	youtube-license-check	Creative Commons license-label classification and its interpretation.
YouTube Video and Audio Download	youtube-download	Video, audio or clips delivered to customer cloud storage.

Install only the task Skills you want, for example:

npx skills add flashdatadev/flashdata-skills --skill google-search --skill youtube-transcript

The CLI's --list option lists available Skills before installing. Each selected Skill is self-contained; sibling Skills are not required. Skill names are shared across the ecosystem, so review an existing installation before replacing a same-named Skill from another publisher. Public source, installation and skills.sh indexing are separate milestones. Instructions are free; FlashData API queries are paid.

These new top-level Skills are also discoverable by clients that scan the repository's skills/ directory. This source update is not a new Cursor or Gemini marketplace approval. The contained Claude plugin continues to bundle its existing shared research Skill.

The MCP research skill was renamed from flashdata to flashdata-mcp; the flashdata skill in the Skills repository now targets the standalone CLI. Update existing MCP skill installations to the new name. This does not alter your MCP connection or credentials.

Cursor plugin

For a single task, choose one of the 15 independent Cursor plugins. Each has its own manifest, Skill and source-restricted npm server. The root marketplace manifest registers them alongside the combined plugin below; public Marketplace listing remains subject to Cursor review.

This repository also contains a Cursor plugin: the same research Skill plus a connection to the hosted FlashData MCP service. The plugin does not run the local Node.js server or require an npm installation. Marketplace review and listing are separate from this public source release.

Cursor discovers the plugin through .cursor-plugin/plugin.json, its MCP server through mcp.json, and the Skill under skills/flashdata-mcp/. The plugin declares FLASHDATA_API_KEY as a required configuration variable. Set your own key through Cursor's plugin configuration when that interface is available; team admins manage variables in Dashboard → Plugins → Configure. The repository contains only a placeholder, never a working key. Do not replace the placeholder in a committed file or paste a key into Agent chat.

For local development, follow Cursor's local plugin instructions: copy .cursor-plugin/, mcp.json, skills/, assets/, README.md, and LICENSE into ~/.cursor/plugins/local/flashdata/. Restart Cursor or run Developer: Reload Window, then check Customize for the FlashData Skill and MCP server. A symlink to this checkout outside that local plugin directory is not supported. Organization policy can disable local plugin imports.

If your local Cursor setup does not offer plugin variable configuration, connect the hosted MCP service separately using Cursor's supported MCP configuration and protected environment variables. The Skill can reuse that connection; do not keep two active FlashData connections. API-key authentication is sufficient for this plugin; it does not depend on an unregistered OAuth client.

After configuration, invoke /flashdata-mcp and ask: “Quote one Google search using FlashData, but do not run the search.” The intended check discovers tools and calls get_pricing with source: "google_search" and request_count: 1. It is free and does not verify paid retrieval. Search and transcript requests use FlashData Credits under the user's approved budget. Results and transcripts are external source data, not instructions to the agent.

Support: support@flashdata.dev. See Security, FlashData terms, and privacy.

Gemini CLI extension

For a single task, choose one of the 15 independent Gemini extensions. Each has its own repository, sensitive API-key setting, Skill and source-restricted npm server. Repository installation and gallery discovery are verified separately. The combined hosted extension remains available below.

The Gemini CLI extension bundles the same FlashData research Skill and hosted MCP connection. It requires Gemini CLI and a FlashData account; it does not run this repository's local Node.js MCP server or require the local npm package.

Install from the public repository:

gemini extensions install https://github.com/flashdatadev/flashdata-mcp

Review the extension when prompted. Enter your own FlashData API key into the installation setting, not Agent chat. gemini-extension.json declares the key as a sensitive setting so Gemini CLI uses the system keychain and masks the input. The repository contains only an environment-variable placeholder. To change the key later, run gemini extensions config flashdata.

Restart Gemini CLI after installing or changing the configuration. Run gemini extensions list to check the installation, and use /mcp and /skills list in an interactive session to inspect the FlashData connection and Skill. If an existing Gemini MCP setting also uses the name flashdata, that user setting takes precedence; use one intended connection rather than maintaining duplicates.

For a free FlashData check, ask: “Use the FlashData skill to quote one Google search with get_pricing, source google_search, request_count 1. Do not run the search or any other paid query.” Skill activation and tool execution remain subject to your Gemini CLI permissions. The extension is MIT-licensed and has no separate fee. FlashData queries consume your Credits; account reads and pricing checks are free. Gemini model access and its usage limits are separate from FlashData. Google's June 2026 transition notice moves individual/free access to Antigravity CLI; Gemini CLI remains available through supported enterprise licenses and paid API keys. This extension has been validated for Gemini CLI, not Antigravity CLI.

For local development, run gemini extensions link /absolute/path/to/flashdata-mcp and restart the CLI. The extension uses Streamable HTTP (httpUrl) and automatically discovers skills/flashdata-mcp/; no additional commands or persistent context file are required. GitHub installation and Gemini gallery indexing are separate milestones; a public repository is not proof of a live gallery listing.

Claude Code plugin

The Claude plugin bundles the shared research Skill and a hosted MCP connection. Install through FlashData's own GitHub marketplace:

claude plugin marketplace add flashdatadev/flashdata-mcp
claude plugin install flashdata@flashdata

Use Claude Code 2.1.285 or later and enter your key through /plugin configure flashdata@flashdata in an interactive session. The sensitive setting uses Claude Code's secure credential store. Restart, inspect /mcp, then invoke /flashdata:flashdata-mcp and request a free pricing check. Queries use FlashData Credits; model access and fees are separate.

The plugin is contained in plugins/claude/ so it does not ship this repository's top-level executable. Shared Skill, logo, and license copies are generated by npm run sync:claude-plugin; CI checks that they match the originals. Its API-key configuration is for Claude Code; authenticated use in Chat and Cowork requires their connector setup. This GitHub marketplace is independent of Anthropic's official directory, where neither the plugin nor its required separate MCP connector submission has been approved.

Repository layout

bin/                      JSON CLI and stdio MCP executables
src/                      shared tool execution, MCP adapter, API clients and local cache
test/                     isolated CLI, protocol, HTTP security and cache tests
scripts/                  package checks and installation verification
npm/                      15 task package definitions and developer guides
integrations/             Cursor/Gemini task catalog and native example prompts
plugins/cursor/           15 self-contained source-specific Cursor plugins
extensions/gemini/        15 self-contained Gemini extension release directories
.cursor-plugin/marketplace.json Cursor combined and task plugin registry
skills/flashdata-mcp/         portable Agent Skill and research recipes
.cursor-plugin/plugin.json Cursor plugin manifest and variable declaration
mcp.json                  hosted MCP connection for the Cursor plugin
gemini-extension.json     Gemini CLI hosted MCP and sensitive key setting
.claude-plugin/marketplace.json Claude marketplace index
plugins/claude/           contained Claude plugin and generated shared files
assets/logo.svg           FlashData plugin logo
.github/workflows/ci.yml  continuous integration
package.json              package metadata and commands
package-lock.json         reproducible dependency installation
LICENSE                   MIT license
THIRD_PARTY_NOTICES.md    dependency notices
SECURITY.md              vulnerability reporting and trust boundaries

Response formats

Since 0.3.0, local MCP returns Markdown in its text content by default. Original API fields remain in structuredContent for programs; large results instead provide chunk metadata there. Choose a different presentation with a tool argument:

response_format	Text content
omitted or "markdown"	Markdown with source links and returned timestamps
"text"	Indented, readable original fields
"json"	Original JSON text

For example, call google_search with {"query":"battery recycling"} for Markdown, or add "response_format":"json" for JSON. This option also applies to async receipts, batch submissions, job reads and account reads. get_result inherits the initial format. Errors remain structured JSON. Formatting does not repeat the query, change billing, or persist preferences on a job.

These are MCP tool arguments, not HTTP Accept or X-Respond-With headers. REST and SDK calls still default to JSON. The legacy npm CLI also keeps its JSON default. Hosted MCP and pinned task packages are separate releases: inspect their live tool schemas before sending response_format.

The Python examples request JSON when supported and retrieve every result chunk before closing the session. Install each complete skill directory so its example and mcp_response.py helper stay together.

For clients that expose only text, formatted chunk responses include a compact JSON continuation block followed by the readable chunk. Use its result_id and next_offset to finish the result; the complete document is still Markdown or text.

Run locally

Requires Node.js 22.18 or newer and a FlashData API key from a FlashData account. The Management API must support /v2/api-access and its balance, pricing and limits routes. Deploy that server release before connecting this package to an older environment.

Clone the repository and install its dependencies:

git clone https://github.com/flashdatadev/flashdata-mcp.git
cd flashdata-mcp
npm ci
export FLASHDATA_API_KEY='YOUR_API_KEY'
npm start

The process communicates over stdin/stdout; it does not show a web page or interactive prompt. Use node bin/flashdata-mcp.js --help for configuration help. Normal protocol operation writes no banners or request data to stdout or stderr.

For a local clone, configure Claude Desktop (or another stdio MCP client) with an absolute path:

{
  "mcpServers": {
    "flashdata": {
      "command": "node",
      "args": ["/absolute/path/to/flashdata-mcp/bin/flashdata-mcp.js"],
      "env": { "FLASHDATA_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Use the full path to Node if your desktop app cannot find it. On Windows, use an escaped Windows path. Keep credentials in your client's protected configuration, not in a prompt, URL, committed file, or command-line argument.

You can also install the reviewed artifact with npm install /absolute/path/flashdata-dev-mcp-0.3.1.tgz in a separate project and run its node_modules/.bin/flashdata-mcp executable. For npm installation, use the explicit commands below: the package contains two executables.