FlowMCP CLI

Command-line tool for developing, validating, and managing FlowMCP schemas.

Description

FlowMCP CLI is a developer tool for working with FlowMCP schemas — structured API definitions that enable AI agents to interact with external services. The CLI provides schema validation, live API testing, repository imports, and an MCP server mode for integration with AI agent frameworks like Claude Code.

Architecture

flowchart LR
    A[Global: ~/.flowmcp/] --> B[Config + .env + Schemas]
    B --> C[flowmcp init]
    C --> D[Local: project/.flowmcp/]
    D --> E[Groups with Selected Tools]
    E --> F[flowmcp call / run]

Loading

Level	Path	Content
Global	~/.flowmcp/	Config, .env with API keys, all imported schemas
Local	{project}/.flowmcp/	Project config, groups with selected tools

Quickstart

git clone https://github.com/FlowMCP/flowmcp-cli.git
cd flowmcp-cli
npm i
npx flowmcp init

User Commands

Interactive commands for humans. These use prompts, colored output, and guided workflows.

Command	Description
flowmcp init	Interactive setup — creates global and local config
flowmcp help	Show available commands and usage

Mode Availability

init and other development commands are available based on the current mode:

Situation	Mode	init	validate/test	search/add
No local config	null	Yes	Yes	Yes
Config with mode: "agent"	agent	No	No	Yes
Config with mode: "dev"	development	Yes	Yes	Yes

When no local config exists, all commands are available so that flowmcp init can be run to bootstrap a project. Once the config is set to agent mode, only agent commands remain accessible.

Agent Commands

JSON-output commands designed for programmatic consumption by AI agents and scripts.

Schema Management

Command	Description
flowmcp import <url> [--branch name]	Import schemas from a GitHub repository
flowmcp import-registry <url>	Import schemas from a registry URL
flowmcp schemas	List all available schemas and their tools
flowmcp status	Show config, sources, groups, and health info

Validation & Testing

Command	Description
flowmcp validate [path] [--group name]	Validate schema structure against spec 1.2.0
flowmcp test project [--route name] [--group name]	Test default group with live API calls
flowmcp test user [--route name]	Test all user schemas with live API calls
flowmcp test single <path> [--route name]	Test a single schema file

Group Management

Command	Description
flowmcp group list	List all groups and their tool counts
flowmcp group append <name> --tools "refs"	Add tools to a group (creates group if new)
flowmcp group remove <name> --tools "refs"	Remove tools from a group
flowmcp group set-default <name>	Set the default group

Tool Execution

Command	Description
flowmcp call list-tools [--group name]	List available tools in default/specified group
flowmcp call <tool-name> [json] [--group name]	Call a tool with optional JSON input
flowmcp run [--group name]	Start MCP server (stdio transport)

Tool Reference Format

source/file.mjs              # All tools from a schema
source/file.mjs::routeName   # Single tool from a schema

Workflow Example

# 1. Setup
flowmcp init
flowmcp import https://github.com/flowmcp/flowmcp-schemas

# 2. Create project group
flowmcp group append crypto --tools "flowmcp-schemas/coingecko/simplePrice.mjs,flowmcp-schemas/etherscan/getBalance.mjs"
flowmcp group set-default crypto

# 3. Validate and test
flowmcp validate
flowmcp test project

# 4. Use tools
flowmcp call list-tools
flowmcp call coingecko_simplePrice '{"ids":"bitcoin","vs_currencies":"usd"}'

# 5. Run as MCP server
flowmcp run

License

MIT