Skip to main content
Glama

MCPForge

Turn any OpenAPI 3.x REST API into a working MCP server.

MCPForge reads an OpenAPI specification — from a local file or a URL — and exposes every operation as an MCP tool. AI agents that speak MCP (Claude Desktop, and other MCP clients) can then call that REST API without any hand-written integration code. Parameters and request bodies become the tool's input schema; the tool executes the HTTP call and returns the API's response.

Installation

Requires Python 3.10 or newer.

git clone https://github.com/Thegreatprabh/MCPForge.git
cd MCPForge
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

This installs the mcpforge command and its dependencies (mcp — the official MCP Python SDK — pyyaml, httpx).

Verify the install:

mcpforge inspect examples/petstore-mini.yaml

Related MCP server: API-to-MCP Converter

Quickstart

The repo ships with a tiny demo API and a spec for it, so the full flow works with no internet access.

# 1. See the tools a spec would produce (dry run, no server started)
mcpforge inspect examples/petstore-mini.yaml

# 2. Start the demo API in another terminal (foreground, 127.0.0.1:18080)
mcpforge demo

# 3. Generate a config file from the spec
mcpforge generate examples/petstore-mini.yaml --config mcpforge.yaml

# 4. Serve the spec as an MCP server over stdio (for Claude Desktop)
#    --allow-private-hosts is required here: the demo API runs on
#    127.0.0.1, and the default SSRF guard blocks loopback/private hosts.
mcpforge serve examples/petstore-mini.yaml --allow-private-hosts

To point the server at a different API host, pass --base-url:

mcpforge serve examples/petstore-mini.yaml --base-url http://127.0.0.1:18080

Claude Desktop

Add the server to your Claude Desktop configuration:

{
  "mcpServers": {
    "petstore": {
      "command": "/path/to/MCPForge/.venv/bin/mcpforge",
      "args": ["serve", "/path/to/MCPForge/examples/petstore-mini.yaml", "--allow-private-hosts"],
      "env": {
        "MCPFORGE_AUTH_ApiKeyAuth": "your-api-key"
      }
    }
  }
}

For the demo above, start the demo API first (mcpforge demo in another terminal) and keep --allow-private-hosts in args — without it the default SSRF guard blocks the loopback demo API and every tool call fails.

Usage

mcpforge demo [--host 127.0.0.1] [--port 18080]

Starts the demo pet-store API in the foreground, on 127.0.0.1:18080 by default — the same URL the spec in examples/petstore-mini.yaml points at. Run it in a separate terminal before serving the demo spec.

mcpforge inspect <spec>

Lists the tools the spec would expose — one line per tool with its HTTP method, path, description, and required inputs. Starts no server. It makes no network calls for a local-file spec with local refs; a URL spec or a remote $ref is fetched over HTTP(S).

mcpforge generate <spec>

Builds the tools from the spec and writes a ready-to-use config file (default mcpforge.yaml). The generated file never contains secrets.

mcpforge serve <spec>

Runs the MCP server.

mcpforge serve <spec> [--config FILE] [--transport stdio|sse]
                      [--host HOST] [--port PORT] [--base-url URL]
                      [--timeout SECONDS] [--allow-private-hosts]
  • --transport stdio (default): speaks MCP over standard input/output, for Claude Desktop and other local clients. Startup messages go to stderr so stdout stays a clean protocol channel.

  • --transport sse: serves MCP over HTTP with Server-Sent Events (GET /sse, POST /messages/), for remote clients. Defaults to 127.0.0.1:8000.

The spec may also be supplied through --config instead of positionally.

Configuration

Config files are YAML (or JSON). Example — see examples/config.example.yaml for a commented version:

spec: ./openapi.yaml
base_url: https://api.example.com
auth: {}
include: []
exclude: []
timeout: 30.0
max_response_bytes: 1000000
allow_private_hosts: false
transport: stdio
host: 127.0.0.1
port: 8000
server_name: mcpforge

Precedence is CLI flag, then config file, then built-in default. include and exclude are case-insensitive substring filters matched against tool names and operation IDs.

Authentication

MCPForge honours the security schemes declared in the OpenAPI document: API key (header, query, or cookie), HTTP Bearer, and HTTP Basic. Secrets are supplied through environment variables or the config file — never hardcoded — and are never written to logs or error messages.

Environment variable form: MCPFORGE_AUTH_<SCHEME_NAME> — the scheme name upper-cased, with non-alphanumeric characters replaced by _. For a scheme named ApiKeyAuth:

export MCPFORGE_AUTH_APIKEYAUTH="your-api-key"

An environment variable takes precedence over a value in the config file. For Basic auth the value is username:password. Operations whose security requirement cannot be satisfied fail with a clear error naming the scheme, not the secret.

Security

  • SSRF guard (on by default). Requests to private, loopback, link-local, reserved, or multicast hosts are blocked, as are non-HTTP(S) URLs. Hostnames are resolved and every resolved address is checked. Redirect targets are re-checked on every hop (up to 5 redirects). Set allow_private_hosts: true (or --allow-private-hosts) only when you intentionally bridge a local API — the demo needs this flag because it runs on 127.0.0.1.

  • Secrets are never logged. Authorization headers and credential values never appear in output, logs, or error messages.

  • Limits. Each connect/read/write operation times out after timeout (default 30 s) — that is a per-operation timeout, not a total one, so a slow-drip response can run longer in total. Responses are truncated at max_response_bytes (default 1,000,000 bytes).

  • SSE transport has no authentication of its own in v1. Bind it to localhost (the default) or put it behind a reverse proxy that authenticates clients.

How it works

File

What it does

mcpforge/parser.py

Loads OpenAPI 3.x specs (JSON/YAML, file or URL) and resolves $refs, including nested and remote refs

mcpforge/tools.py

Converts operations into MCP tool definitions: sanitised names, input JSON Schemas from parameters and request bodies, include/exclude filtering

mcpforge/auth.py

Resolves credentials from config and environment, applies API key / Bearer / Basic auth per the spec's security schemes

mcpforge/http.py

SSRF-guarded HTTP execution with timeout, redirect re-checking, and response truncation

mcpforge/server.py

MCP server wiring on the official MCP Python SDK (stdio and SSE transports)

mcpforge/config.py

Config file loading and validation, CLI-over-file-over-default merging

mcpforge/cli.py

The generate / serve / inspect / demo command-line interface

mcpforge/demo.py

A tiny stdlib-only demo REST API (pet store) for end-to-end testing

mcpforge/errors.py

Shared error types

examples/petstore-mini.yaml

Example OpenAPI spec for the demo API (4 operations, API-key auth on POST)

examples/config.example.yaml

Commented example configuration

tests/

Unit tests plus an end-to-end test that drives the real server against the real demo API over stdio

What v1 does not do

  • OAuth2 / OpenID Connect flows are not supported. Operations that require them fail with a clear error.

  • Request bodies are supported for application/json only. Other content types are ignored.

  • Remote $refs are fetched over HTTP(S) when reachable; an unreachable remote ref is an error, not a silent skip.

  • Response bodies are returned as text (JSON is not re-shaped or validated against the spec's response schemas).

  • No streaming responses and no MCP resources or prompts — tools only.

  • Tool names are sanitised to the MCP pattern ^[A-Za-z0-9_-]{1,64}$; long or unusual operation IDs are shortened, with numeric suffixes for collisions.

  • The demo API declares ApiKeyAuth on POST /pets but does not validate the key — it exists to demonstrate header injection, not to enforce authentication.

Development

# Run the full test suite (222 tests, stdlib unittest)
.venv/bin/python -m unittest discover -s tests

# Run the end-to-end test only
.venv/bin/python -m unittest tests.test_e2e

The suite includes unit tests for parsing, tool generation, auth, the SSRF guard, HTTP execution, config, the server, and the CLI, plus an end-to-end test that starts the MCP server against the demo API over stdio and calls tools through a real MCP client session. A fresh-copy check (copy the tree to a clean directory, fresh virtualenv, pip install -e ., full suite) passes with the same result.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Converts any OpenAPI/Swagger API specification into MCP tools that AI assistants can use to interact with the API.
      19 npm
      7
      MIT