vulcai-mcp-forge-cli 0.1.25

Generate MCP servers instantly from any OpenAPI, GraphQL, codebase, CLI or website

vulcai-mcp-forge-cli

Generate production-ready MCP servers instantly from any source — OpenAPI spec, GraphQL schema, codebase, CLI tool, or website.

pip install vulcai-mcp-forge-cli
mcp-forge run https://petstore3.swagger.io/api/v3/openapi.json

---

What it does

mcp-forge analyses your source, extracts all callable operations, optionally enriches them with an LLM, and writes a fully working MCP server (server.py + requirements.txt) ready to plug into Claude Desktop, Claude Code, Cursor, VS Code or any MCP-compatible client.

---

Supported sources

Source	Auto-detected when	Example
OpenAPI / Swagger	URL or file ending in .json, .yaml, .yml	mcp-forge run https://api.example.com/openapi.json
GraphQL	URL contains graphql or ends with /graphql	mcp-forge run https://api.example.com/graphql
Codebase	Local directory path	mcp-forge run ./my-project
CLI application	Command name (no slashes, no http)	mcp-forge run git
Website	http:// or https:// URL without spec extension	mcp-forge run https://example.com

Supported languages for codebase analysis: Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, C#, PHP, Ruby, Kotlin, Swift, Scala, Dart, Elixir, R, Fortran, Bash, PowerShell, Groovy, Julia, Lua, COBOL.

---

Installation

Requirements: Python 3.11+ · Node.js 18+ · uv

pip install vulcai-mcp-forge-cli

Install uv (used to run generated servers):

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Website scraping support (JS-heavy pages / SPAs — requires Playwright):

pip install "vulcai-mcp-forge-cli[web]"
playwright install chromium

---

License key

Get your license key at api.mcp-forge.vulcai.io then register it once in your project directory:

mcp-forge set-license mfg_live_...

This saves the key to a .env file and it will be picked up automatically on every mcp-forge run call.

---

Quick start

# OpenAPI from URL
mcp-forge run https://petstore3.swagger.io/api/v3/openapi.json

# GraphQL
mcp-forge run https://countries.trevorblades.com/graphql

# Local codebase
mcp-forge run ./my-python-project

# CLI tool
mcp-forge run git

# Website
mcp-forge run https://docs.example.com

# Custom output and server name
mcp-forge run https://api.example.com/openapi.json --output ~/mcp-servers --name my_api

The generated server is written to ../mcp-forge-output/<server_name>/ by default.

---

CLI reference

mcp-forge run <source>

Option	Values	Description
--mode, -m	auto · semi · guided	Generation mode — auto runs silently, semi prompts on ambiguity, guided is fully interactive
--type, -t	openapi · graphql · codebase · cli_app · website	Force source type instead of auto-detect
--output, -o	<path>	Output directory (default: ../mcp-forge-output/)
--name, -n	<string>	Override the generated server name
--name-style, -ns	short · exhaustive	Tool naming style
--api-key	<string>	Anthropic API key (overrides ANTHROPIC_API_KEY)
--local	flag	Force local pipeline — no call to the Vulcai API
--no-llm	flag	Skip LLM enrichment — generate from raw discovery only
--config, -c	<file.yaml>	Load options from a YAML config file (default: mcp-forge.yaml if present)
--smoke-test	flag	Run a smoke test automatically after generation
--functional-test	flag	Start the server and run a full MCP functional test after generation

mcp-forge set-license <key>

Save your license key to .env in the current directory.

mcp-forge set-license mfg_live_abc123...

mcp-forge test <server.py>

Launch MCP Inspector on a generated server. Opens in your browser. Accepts Windows backslash paths.

mcp-forge test output/my_server/server.py

mcp-forge smoke-test <server_dir>

Validate a generated server without starting it. Checks: server.py present, Python syntax valid, importable, mcp object present, at least 1 @mcp.tool registered, VERSION file consistency.

mcp-forge smoke-test output/my_server

mcp-forge functional-test <server_dir>

Start the server and communicate with it via JSON-RPC / stdio — exactly like a real MCP client. Verifies: server starts, MCP handshake succeeds, tools/list returns ≥1 tool, count matches VERSION file.

Option	Description
--timeout, -t	Max wait time per phase in seconds (default: 15)

mcp-forge functional-test output/my_server --timeout 30

mcp-forge evaluate <server.py>

Evaluate the quality of a generated server using LLM analysis. Produces a detailed quality report.

Option	Description
--context, -C <string>	Additional context — source spec, use case, expected behaviour
--json	Output raw JSON (useful for CI/CD pipelines)
--save, -s <file.json>	Save the JSON report to a file
--api-key <string>	Anthropic API key (overrides ANTHROPIC_API_KEY)

mcp-forge evaluate output/my_server/server.py --context "Petstore API" --save report.json

mcp-forge list

List all generated MCP servers in the output directory. Displays name, generation date, source and tool count.

Option	Description
--output, -o <path>	Directory to inspect (default: ../mcp-forge-output/)

mcp-forge list

mcp-forge info

Display version info, supported source types and current configuration.

mcp-forge --version

Print the installed version and exit.

---

Generation modes

Mode	Description
auto	Fully automatic — no prompts
semi	Pauses on ambiguity, interactive where needed
guided	Step-by-step with full control over every tool

---

LLM enrichment

By default, mcp-forge calls the Vulcai API to enrich tool names and descriptions using Claude. Set your license key with mcp-forge set-license — no Anthropic key needed in cloud mode.

To run fully locally (requires [engine] extras — not publicly distributed):

mcp-forge run https://api.example.com/openapi.json --local

To skip enrichment entirely:

mcp-forge run https://api.example.com/openapi.json --no-llm

---

Configuration file

Create mcp-forge.yaml in your project root:

source: https://api.example.com/openapi.json
mode: auto
output: ../mcp-servers
name: my-api-server
name_style: short
no_llm: false
functional_test: true

CLI flags always override the config file. Use a custom path with --config path/to/config.yaml.

---

Environment variables

Variable	Description
FORGE_LICENSE_KEY	Your mcp-forge license key. Set automatically by mcp-forge set-license.
FORGE_API_URL	Override the Vulcai API endpoint — useful for on-premise deployments.
FORGE_MODE	Set to local to always use the local pipeline.
ANTHROPIC_API_KEY	Anthropic API key — only needed when running the local pipeline with LLM enrichment.

---

Connecting to AI clients

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "my_api": {
      "command": "uv",
      "args": ["run", "--with", "mcp", "mcp", "run", "server.py"],
      "cwd": "/path/to/mcp-forge-output/my_api"
    }
  }
}

Restart Claude Desktop — your tools appear automatically.

Claude Code (CLI)

claude mcp add my_api uv -- run --with mcp mcp run server.py \
  --cwd /path/to/mcp-forge-output/my_api

Cursor

Open Settings › MCP › Add new global MCP server:

{
  "my_api": {
    "command": "uv",
    "args": ["run", "--with", "mcp", "mcp", "run", "server.py"],
    "cwd": "/path/to/mcp-forge-output/my_api"
  }
}

VS Code (Copilot / Continue)

In .vscode/mcp.json:

{
  "servers": {
    "my_api": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--with", "mcp", "mcp", "run", "server.py"],
      "cwd": "/path/to/mcp-forge-output/my_api"
    }
  }
}

Windsurf

Open Settings › Cascade › MCP servers › Add Server:

{
  "my_api": {
    "command": "uv",
    "args": ["run", "--with", "mcp", "mcp", "run", "server.py"],
    "cwd": "/path/to/mcp-forge-output/my_api"
  }
}

Generic (any MCP-compatible client)

All clients implementing the MCP spec accept a STDIO transport:

command : uv
args    : run --with mcp mcp run server.py
cwd     : /path/to/mcp-forge-output/<server_name>
env     : { "MY_API_KEY": "..." }   ← optional, for authenticated APIs

Authenticated APIs: if your API requires credentials, set them in the env block. The generated server.py reads credentials from environment variables — no secrets are hardcoded.

---

CI/CD integration

- name: Generate MCP server
  run: |
    pip install vulcai-mcp-forge-cli
    mcp-forge run https://api.example.com/openapi.json --mode auto --no-llm
    mcp-forge smoke-test ../mcp-forge-output/my_api

---

License

MIT — see LICENSE.