FlowLeap CLI MCP server
Commit Nov 2, 2026Enables AI agents to perform patent searches, academic literature queries, and full-corpus patent analytics via an MCP server or bundled agent skills.
Also known as flowleap-ai/flowleap-cli
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 2, 2026
- License
- MIT
What is FlowLeap CLI MCP?
FlowLeap CLI enables AI agents to perform patent searches, academic literature queries, and full-corpus patent analytics via an MCP server or bundled agent skills.
Summary generated from the project's README
About FlowLeap CLI MCP server
FlowLeap CLI provides a unified interface for patent and academic research, designed for both human developers and AI agents. It functions as a command-line tool and an MCP server that connects to the FlowLeap Patent AI backend. Users can access patent searches across the EPO and USPTO, academic literature via Semantic Scholar and arXiv, and non-patent literature through OpenAlex. The server operates via stdio and can be integrated into various environments including Claude Code, Cursor, Codex, and Gemini CLI.
To use the data features, an active FlowLeap account is required, though a 7-day free trial is available. Some specific data sources like EPO OPS and USPTO ODP require users to provide their own API keys. The system includes specialized tools for full-corpus analytics, OCR for document text extraction, and PATSTAT workflows for portfolio analysis. It also offers unique agent capabilities through bundled skills that can be installed directly into an agent's workspace to provide structured documentation and rules.
What you can do with it
- 1Perform patent searchesAn AI agent can search for specific technologies across EPO and USPTO databases using natural language queries.
- 2Analyze patent portfoliosA developer can request a detailed analysis of an applicant's patent portfolio over a specific timeframe.
- 3Extract text from documentsYou can use the OCR tool to convert patent documents or images into markdown text.
- 4Query academic literatureAn agent can find relevant research papers in academic databases to supplement patent findings.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
FLOWLEAP_API_KEY
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableflowleap-ai/flowleap-cli is public and reachablegithub.com/flowleap-ai/flowleap-cli ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-02github.com/flowleap-ai/flowleap-cli ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFlowLeap CLI
One CLI + MCP server for FlowLeap Patent AI — built for humans and AI agents.
flowleap puts the FlowLeap Patent AI backend in your terminal: patent search across EPO and USPTO, natural-language query building, academic and non-patent literature, patent-law reference search, enriched citation data, OCR, full-corpus analytics, and one-call patent snapshots. The same binary serves every backend tool to AI agents — as a stdio MCP server (flowleap mcp) and as bundled Agent Skills (flowleap skills install) for Claude Code, Codex, Cursor, and Gemini CLI.
Quick Start
# 1. Install (more channels under "Installation" below)
npm i -g flowleap
# 2. Authenticate — OAuth 2.0 device flow, opens your browser
flowleap auth login
# 3. First query
flowleap patent search --query "solar panel efficiency" --limit 5
Verify your setup any time:
flowleap doctor
doctor checks config, credentials, and backend reachability, and tells you what to fix.
Access & Pricing
The CLI itself is open source (MIT) and free to install. The patent-data commands call the FlowLeap backend, which requires:
- A FlowLeap account with an active plan. Every new account starts a free 7-day trial at sign-up — no credit card required; after it, subscribe at flowleap.co/pricing.
- Without an active plan, data commands return HTTP 402 and exit with code 4. In
--jsonmode the error envelope carries a structuredsubscriptionHint—{ requiresHumanIntervention: true, upgradeUrl, message }— with the upgrade URL. This is expected behavior, not a bug: agents should surface the URL to a human rather than retry. - All
/v1data routes share a rate limit of 60 requests/minute/user. Exceeding it returns HTTP 429 (exit code 6) with arateLimitHintcarryingretryAfterSeconds.
Some data sources additionally need your own patent-data keys — free signups at each office: EPO OPS (key + secret) and USPTO ODP (API key). Run flowleap setup for the guided wizard, or see flowleap keys --help. provider_keys_required / provider_keys_invalid / trial_budget_exhausted are the wire codes that name them in error envelopes (the last one meaning today's shared trial data budget is spent — it resets daily, and your own free keys lift it permanently).
Agent behavior when a key is missing (the key-gate doctrine, shipped in full in the flowleap-keys skill): a provider_keys_required error is a user-action stop for that office, never an exhausted route. An agent must not substitute web-scraped patent data for the gated office — searches and single-document reads alike — and must not frame the free key as a paywall. With the other office live it delivers those results in full, names the gap as a missing-key gap rather than a coverage finding, and asks once at the end of the turn; it never silently narrows a prior-art or FTO scope to the office whose key happens to be set. Keyless commands (patstat, academic, npl) stay available meanwhile, offered as different data rather than a replacement for live patent search. A gate is read, never inferred: only that explicit code means gated, so an empty result, a truncated payload, or a 5xx keeps the normal retry paths. Once the key is added, only the previously gated office is re-run — no restart, no new session.
doctor, health, auth, and keys test work without a subscription, so you can always diagnose your setup.
Use with AI Agents
Two integration paths, both embedded in the binary — no network needed to install:
- MCP server:
flowleap mcpserves every backend tool over stdio MCP. Tools are mirrored live from the backend's/v1/toolsregistry, so new backend tools appear without a CLI update. - Agent Skills:
flowleap skills installwrites SKILL.md documentation (or a condensed rules file, depending on the harness) into the location your agent auto-loads.
Authenticate once before wiring either path (flowleap auth login, or set FLOWLEAP_API_KEY for headless use). An unauthenticated MCP server still starts, but every tool call returns an error explaining how to log in.
Beside the tools, flowleap mcp serves the backend's PATSTAT doctrine. It serves six resources: the semantic model (flowleap://patstat/semantic-model), its index (flowleap://patstat/semantic-model/index), the verified examples (flowleap://patstat/examples), and three workflows (flowleap://patstat/workflow/portfolio-analysis, …/guarded-sql, …/graph). It also serves three prompts, one per workflow: patstat-portfolio-analysis, patstat-guarded-sql and patstat-graph. One logical table of the model is the resource template flowleap://patstat/semantic-model/view/{name}, with the names taken from the index; the server reads a view from the backend at its first read and keeps it until it stops. The set of six documents is fixed in the binary, so a new backend workflow needs a CLI release. Their content is live: the server reads each document from the backend at startup and serves it verbatim, so a doctrine edit reaches agents at the next server start. In Claude Code, the prompts appear as /mcp__flowleap__<name> slash commands and the resources attach with @. A document that the backend refuses (the PATSTAT docs route needs an active plan) is skipped and logged to stderr; the rest keep serving. The server does not retry a skipped document: restart it to load again.
Verify readiness any time with the one-command diagnostic — it checks backend reachability, auth, patent-data keys, the live tool count, and the resource and prompt counts, and exits nonzero with fix instructions when something is missing:
flowleap mcp --check
Claude Code
# MCP server
claude mcp add flowleap -- flowleap mcp
# and/or skills (full SKILL.md directories)
flowleap skills install # user-level: ~/.claude/skills
flowleap skills install --target claude-project # this project: ./.claude/skills
Codex
flowleap skills install --target codex # marked block in ./AGENTS.md
MCP server — add to ~/.codex/config.toml:
[mcp_servers.flowleap]
command = "flowleap"
args = ["mcp"]
Cursor
flowleap skills install --target cursor # ./.cursor/rules/flowleap.mdc
MCP server — add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):
{
"mcpServers": {
"flowleap": { "command": "flowleap", "args": ["mcp"] }
}
}
Gemini CLI
flowleap skills install --target gemini # marked block in ./GEMINI.md
Any other MCP-capable harness works the same way: run flowleap with the single argument mcp as a stdio server.
After upgrading the CLI, refresh every recorded skill install in one go:
flowleap skills update
Keeping skills fresh (and which channel to use)
User-scope skills win. In Claude-family harnesses, a skill in ~/.claude/skills
(or a project's .claude/skills) shadows a same-named skill provided by a plugin
or marketplace pack — the user copy is loaded and the packaged one is ignored, even
when the packaged one is newer. So a one-time flowleap skills install can silently
pin you to a stale copy of a skill while the packaged version moves on.
To stay current:
- Pick one channel per machine. Inside the FlowLeap IDE, prefer the marketplace
packs — they auto-update. Use
flowleap skills installfor other harnesses (Codex, Cursor, Gemini CLI, or plain Claude Code) — don't run both for the same skills. - Re-running install refreshes its own copies.
flowleap skills installcompares each installed skill against the bundled one via a content digest recorded in.flowleap-skills-manifest.json: copies it wrote that you haven't touched are refreshed in place; skills you've edited locally are left alone and reported (pass--forceto overwrite those too). Skills it never installed are never touched. - Refresh everything after upgrading with
flowleap skills update, and check status any time withflowleap doctor— itsskillssection flags installs made by an older CLI.
Commands
| Command | Description |
|---|---|
doctor |
Check CLI config, auth, and backend reachability |
setup |
Interactive onboarding: backend check, auth, patent-data keys (human-only) |
keys |
Manage patent-data keys (EPO OPS, USPTO ODP): set, list, test, rm |
init |
Store initial CLI configuration (base URL) |
auth |
Login (OAuth device flow), logout, status, personal API tokens |
api |
Profile, usage, and the raw authenticated API escape hatch |
health |
Public backend health probes (api, cache, redis, …) |
patent |
Search patents (EPO) with CQL you write yourself |
ops |
Direct EPO OPS data: search, biblio, claims, description, family, legal, abstract |
uspto |
USPTO Open Data Portal: search, grants, applications, continuity |
academic |
Search academic literature (Semantic Scholar, arXiv) |
npl |
Search non-patent literature (OpenAlex) |
citation |
USPTO enriched citation data: search, forward, stats, novelty |
analytics |
Full-corpus patent analytics (filing trends, countries, assignees, CPC) |
patstat |
PATSTAT analytics: portfolio aggregates for one applicant, guarded SQL, and graph — a named node and the relationships around it |
ocr |
Extract text from a PDF, image, or document via OCR (file or URL) |
compare |
Compare 2–10 patents side by side (bibliography) |
figures |
List a patent's drawings/figures; save image data with --out |
summary |
One-call patent snapshot: bibliography, legal status, family, term |
timeline |
Chronological prosecution timeline for a patent |
convert-number |
Convert a patent number between formats (epodoc, docdb, original) |
tools |
Discover and run backend tools (agent-first /v1/tools facade) |
mcp |
Serve backend tools over the Model Context Protocol (stdio) |
skills |
List, install, and update bundled agent skills (multi-harness) |
config |
Manage CLI configuration |
upgrade |
Upgrade the CLI itself (channel-aware: npm/binary/cargo); alias update |
A sampler:
# Patents
flowleap patent search --query "lithium battery recycling" --limit 5
flowleap uspto search --query "wireless charging" --limit 3
flowleap uspto grant 11800000
flowleap ops biblio EP1234567
flowleap ops claims EP1234567 --lang en
# One-call verbs
flowleap summary EP1000000
flowleap timeline EP1000000
flowleap compare EP1000000 US5443036
flowleap figures EP1000000 --out fig1.png
flowleap convert-number US5443036.A --to epodoc
# Literature, citations, analytics
flowleap academic search "machine learning patent classification"
flowleap npl "battery thermal management" --limit 10
flowleap citation search 16000001 --size 20
flowleap analytics --keyword battery --country US --date-from 2020-01-01
flowleap patstat portfolio Siemens --from-year 2015 --to-year 2024
flowleap patstat graph resolve EP3477840
flowleap patstat graph patent EP3477840
flowleap patstat graph applicant 98765
flowleap patstat graph neighborhood EP3477840 --depth 2 --edge-types cites,cited_by
flowleap patstat graph path EP3477840 US5960411
flowleap patstat graph explain pat:56123456
# Documents
flowleap ocr ./office-action.pdf > office-action.md
# Agent-first tool facade (same registry the MCP server mirrors)
flowleap tools list
flowleap tools describe get_patent_summary
flowleap tools run search_patents --input '{"query":"ti=solar","limit":3}'
# Raw API escape hatch — only when a high-level command is missing
flowleap --json api request get /v1/health
flowleap --json api request post /v1/patent-search --body-file request.json --dry-run
Installation
npm / pnpm / yarn:
npm i -g flowleap
The npm package has no install scripts. The native binary is downloaded on first run from the matching GitHub release, verified against the release's sha256 checksums.txt before it executes, and the package is published with npm provenance attesting the exact repo, commit, and CI run that built it.
Shell installer (macOS / Linux):
curl -fsSL https://raw.githubusercontent.com/flowleap-ai/flowleap-cli/main/install.sh | sh
The script detects your platform, downloads the latest release binary, and verifies its sha256 against the release's checksums.txt before installing to /usr/local/bin.
From source (requires Rust):
cargo install --git https://github.com/flowleap-ai/flowleap-cli.git
Prebuilt release binaries cover macOS (x86_64, arm64), Linux (x86_64 and arm64 glibc, plus a static flowleap-linux-x86_64-musl build for Alpine/containers — download it directly from the releases page), and Windows (x86_64).
Downloading a binary from the releases page on macOS: the release binaries are not notarized, so Gatekeeper quarantines anything the browser downloaded and refuses to run it ("cannot be opened because the developer cannot be verified"). Clear the quarantine attribute after downloading:
xattr -d com.apple.quarantine ./flowleap-darwin-arm64
chmod +x ./flowleap-darwin-arm64
The shell installer and npm paths above are unaffected — neither marks the binary as browser-downloaded.
Updating: flowleap upgrade updates the CLI on whichever channel installed it — no need to remember which. It runs npm i -g flowleap@latest for npm installs, self-updates the raw binary in place (downloading the platform release asset and verifying its sha256 against checksums.txt before an atomic swap, exactly like first-run), and prints the cargo install … --force command for source installs. Use flowleap upgrade --check (add --json for agents) to see the channel and available version without changing anything.
Installed skill files are copies, so an upgrade leaves them behind. A raw-binary self-update refreshes them with the new build automatically; on the other channels run flowleap skills update yourself once the upgrade finishes — until you do, agents read skill files that document retired commands.
Authentication
Every authenticated request sends Authorization: Bearer <credential>. Three ways to supply one:
- OAuth 2.0 device flow (recommended for humans):
flowleap auth loginprints a device code and opens your browser to approve it. - Personal API token (recommended for agents/CI):
flowleap auth create-token --name my-agent --storemints a revocablefl_pat_…token. List withflowleap auth tokens, revoke withflowleap auth revoke-token <id>. - Environment variables:
FLOWLEAP_API_KEY(anfl_pat_…token) orFLOWLEAP_TOKEN.
Credentials are stored in ~/.config/flowleap/credentials.toml (mode 0600).
flowleap auth status # is the credential present AND working?
flowleap auth logout # clear everything, including patent-data keys
flowleap auth logout --session-only # keep API key + patent-data keys
auth status verifies the credential against the backend rather than only
reporting that one is stored, and exits with the verdict so scripts can branch
on $?:
| State | Meaning | Exit |
|---|---|---|
valid |
The backend accepted the credential | 0 |
rejected |
Present but refused (HTTP 401) — expired, revoked, or wrong | 3 |
absent |
No credential configured | 3 |
unverified |
Could not check (backend unreachable, or --dry-run) |
7 (0 for --dry-run) |
An unreachable backend is reported as "could not verify", never as invalid —
the absence of a verdict is not evidence against the credential. --json emits
the same verdict as { verification: { state, checked, reason? } }, where
checked says whether a live check actually reached a conclusion.
Every device-flow login also runs a store-time TTL guard: it decodes the
session token's exp claim and refuses to write it to credentials.toml if
under 10 minutes remain, printing the actual lifetime and exiting 3 rather
than silently persisting a credential that's already effectively dead
(flowleap-backend#254). Non-JWT tokens (e.g. fl_pat_…) are unaffected.
CI / Headless Use
Mint a token once on your machine, then export it wherever the CLI runs:
# once, interactively (token creation requires an OAuth session, not an API token)
flowleap auth login
flowleap auth create-token --name ci-agent
# in CI: export the fl_pat_… token
export FLOWLEAP_API_KEY="fl_pat_..."
flowleap --json patent search --query "battery cooling" --limit 3
Headless notes:
--yes(orFLOWLEAP_ASSUME_YES=1) skips confirmation prompts, e.g. the credential guard that fires when--base-urlpoints at a non-FlowLeap host. Non-TTY,--json, and--dry-runruns are never blocked on a prompt.- Provider keys can come from env too:
FLOWLEAP_EPO_KEY,FLOWLEAP_EPO_SECRET,FLOWLEAP_USPTO_KEY. - API tokens cannot mint further tokens (backend-enforced).
JSON Output & Exit Codes
Add --json (or --output json) for stable machine-readable output — recommended for all agent and script use. Success responses carry the command's data; failures print a JSON error envelope on stdout:
{ "ok": false, "error": { "message": "…" } }
Envelopes may carry additive structured hints: subscriptionHint (402 — upgrade URL, needs a human), providerKeysHint (missing/rejected patent-data keys, or the trial's shared data budget spent for today — needs a human, do not retry, and do not substitute web-scraped data for the gated office; see Access & Pricing), rateLimitHint (429 — wait retryAfterSeconds, then retry), and endpointGoneHint (410 — the build is stale; upgrade rather than retry, and the hint names the successor endpoint). Human/table output renders the same hints as info boxes on stderr, and prints the backend's trial_data_budget_low success warning (budget ≥80% spent) as a stderr note.
Every run exits with a documented code, so scripts can branch on $? without parsing JSON:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Generic failure |
| 2 | Usage error (bad flags/arguments) |
| 3 | Auth required (HTTP 401, or no credential configured at all) — flowleap auth login or set FLOWLEAP_API_KEY |
| 4 | Subscription required (HTTP 402) — see subscriptionHint |
| 5 | Not found (HTTP 404) |
| 6 | Rate limited (HTTP 429) — back off, see rateLimitHint |
| 7 | Network failure reaching the backend |
| 8 | Endpoint gone (HTTP 410) — this build calls a retired endpoint; run flowleap upgrade, see endpointGoneHint |
| 9 | Patent-data keys required/rejected, or the trial data budget exhausted — a human must add EPO/USPTO keys; see providerKeysHint, do not retry (the budget variant alone also lifts at its resetsAt) |
Two details worth knowing:
- The local auth guard. A command that needs a credential and finds none
fails before anything is sent. It exits 3 like a rejected 401, and its
--jsonenvelope carrieserror.code: "unauthenticated"— the one failure that never reaches the backend still names itself in the closed code registry. - Exit 9 covers
keystoo.flowleap keys testandflowleap keys setexit 9 on a rejected or missing provider key, the same code a key-gated data command returns.
Use --dry-run to see the exact method, URL, auth status, and JSON body the CLI would send — the safest way to debug request shape:
flowleap --json patent search --query "battery cooling system" --limit 1 --dry-run
Add --dry-run-redacted when the body contains an unpublished invention,
claim, search query, document text, or URL. The output retains the JSON shape
but replaces sensitive values with [REDACTED].
Search queries are written by the caller (you or your agent), locally — there
is no server-side query builder, so an unpublished invention description never
has to leave the machine to become a query. The bundled flowleap-patent and
flowleap-uspto skills carry the query-writing method (term extraction,
discriminating terms, and the mandatory count probe).
The full contract (hint schemas, endpoint list, agent protocol) lives in AGENTS.md.
Cookbook: Recipe Skills
The CLI bundles 15 multi-step workflow recipes (recipe-* skills). Install them with flowleap skills install and your agent can run each end to end:
| Recipe | What it does |
|---|---|
recipe-prior-art-search |
Comprehensive prior art search: query generation, dual EPO/USPTO search, academic sweep, deep dives on closest hits |
recipe-patent-landscape |
Map a technology area: scoped searches, key players, recent activity, full-corpus filing analytics |
recipe-freedom-to-operate |
FTO/clearance search: per-feature queries, blocking-patent search, legal-status and claims checks |
recipe-find-better |
Post-grant: read the Examiner Baseline, run three logged expansion tracks, compare the examiner's best art with the art found per claim |
recipe-claim-analysis |
Extract and analyze a patent's claims with full context and element decomposition |
recipe-patent-to-report |
Extract everything about one patent into a structured report (dossier) |
recipe-academic-literature-review |
Technology review combining scholarly literature and a matching patent sweep |
recipe-invention-disclosure |
Turn an inventor conversation into a complete invention disclosure form with novelty pre-check |
recipe-claim-drafting |
Draft claims grounded in the closest prior art and checked against MPEP/EPO formal rules |
recipe-office-action-response |
OCR an office action, pull cited references, map rejections, ground arguments in guidelines |
recipe-invalidity-analysis |
Build a prior-art invalidity case: priority date, element hunt, X/Y/A invalidity chart |
recipe-infringement-charting |
Element-by-element infringement claim chart against an accused product |
recipe-maintenance-fees |
US maintenance-fee status: fee windows from the grant date, paid fees from USPTO transaction events, the next deadline with surcharge dates |
recipe-custom-dashboard |
Turn verified patent data into an offline single-file HTML dashboard, every number computed in code, with a provenance footer |
recipe-audit-report |
Auditable record of AI-assisted research: command log, provenance, AI-usage disclosure |
FlowLeap CLI MCP questions
How do I use FlowLeap with AI agents?
You can use it as an MCP server via flowleap mcp or install bundled Agent Skills for tools like Claude Code, Cursor, and Gemini CLI using flowleap skills install.
Does using the CLI require a subscription?
The CLI is open source and free to install, but patent-data commands require an active FlowLeap account plan. New accounts include a free 7-day trial.
What should an agent do if a patent-data key is missing?
The agent should treat a provider_keys_required error as a request for user intervention rather than a coverage gap, asking the user to provide the necessary key.
How can I verify my CLI configuration and connectivity?
Run the flowleap doctor command to check your configuration, credentials, and backend reachability.