Skip to main content
Glama
README.md
# 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.

```bash
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:

```bash
mcpforge inspect examples/petstore-mini.yaml
```

## Quickstart

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

```bash
# 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`:

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

### Claude Desktop

Add the server to your Claude Desktop configuration:

```json
{
  "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:

```yaml
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`:

```bash
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 `$ref`s, 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 `$ref`s** 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

```bash
# 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.