Skip to content
Back to search

auto-mcp

Transform any OpenAPI/Swagger definition into a fully-featured Model Context Protocol (MCP) server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/brizzai--auto-mcp/badge.svg)](/listings/brizzai--auto-mcp)

HTML

<a href="/listings/brizzai--auto-mcp"><img src="/api/listings/brizzai--auto-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 180 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Auto MCP
  2. [Visit the Auto MCP Homepage](https://automcp.brizz.ai/)
  3. [![Go Report Card](https://goreportcard.com/badge/github.com/brizzai/auto-mcp)](https://goreportcard.com/report/github.com/brizzai/auto-mcp)
  4. [![GitHub release (latest by date)](https://img.shields.io/github/v/release/brizzai/auto-mcp)](https://github.com/brizzai/auto-mcp/releases/latest)
  5. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  6. [![Go version](https://img.shields.io/github/go-mod/go-version/brizzai/auto-mcp)](https://golang.org/doc/devel/release.html)
  7. [![Container Registry](https://img.shields.io/badge/container-ghcr.io-blue)](https://github.com/brizzai/auto-mcp/pkgs/container/auto-mcp)
  8. [![Build Status](https://img.shields.io/github/actions/workflow/status/brizzai/auto-mcp/auto-mcp-tests.yml?branch=master)](https://github.com/brizzai/auto-mcp/actions/workflows/auto-mcp-tests.yml)
  9. Transform any OpenAPI/Swagger definition into a fully-featured **Model Context Protocol (MCP)** server – ready to run locally, inside Claude Desktop, or in the cloud.
  10. The service reads a Swagger (OpenAPI v2) or OpenAPI v3 document, generates routes on-the-fly, proxies requests to the upstream endpoint you configure, and exposes them through MCP using either the **STDIO** or **HTTP** or **SSE** transport defined in the [MCP specification](https://modelcontextprotocol.io/introduction).
  11. ---
  12. ## ✨ Why Auto MCP?
  13. - **Zero boiler-plate** – bring your `swagger.json` and start serving.
  14. - **Flexible deployment** – run as a CLI, long-lived daemon, or within Docker/Kubernetes.
  15. - **All transport modes** –
  16. - `stdio` (default).
  17. - `http` - StreamableHttp, newest MCP prototcol.
  18. - `sse` – self-hosted long-running event source.
  19. - **Pluggable auth** – bearer token, basic auth, API keys, OAuth2 or no auth.
  20. - **Runtime configuration** – YAML file, CLI flags, or environment variables (prefixed `AUTO_MCP_`).
  21. ---
  22. ## 🛠️ Using Auto MCP
  23. Easily tailor your Swagger/OpenAPI file for optimal MCP integration. The MCP Config Builder lets you:
  24. - **Edit endpoint descriptions** for clearer, more helpful documentation.
  25. - **Filter out unnecessary routes** to streamline your API exposure.
  26. - **Preview and customize** how endpoints appear to LLMs and clients.
  27. - **Generate an adjustment file** (`--adjustment-file`) for use with Auto MCP, applying your customizations automatically.
  28. ![MCP Config Builder](docs/mcp-config-builder.gif)
  29. ### How it works
  30. 1. **Install the MCP Config Builder:**
  31. ```bash
  32. go install ./cmd/mcp-config-builder
  33. ```
  34. This will build and install the `mcp-config-builder` binary to your `$GOPATH/bin` (usually `~/go/bin`). Make sure this directory is in your `PATH`.
  35. 2. **Launch the tool:**
  36. ```bash
  37. mcp-config-builder --swagger-file=/path/to/swagger.json
  38. ```
  39. 3. **Interactively review and edit** endpoints in a user-friendly TUI (Terminal User Interface).
  40. 4. **Save your adjustments** to a file for future use or sharing.
  41. 5. **Run Auto MCP** with your adjustment file to apply your customizations:
  42. ```bash
  43. auto-mcp --swagger-file=/path/to/swagger.json --adjustment-file=/path/to/adjustments.json
  44. ```
  45. ---
  46. ## 📚 Use Cases
  47. 1. **Rapid Prototyping:** Wrap any REST API as an MCP server in seconds—ideal for testing ideas or building AI tools fast.
  48. 2. **Bridge Legacy Services:** Expose legacy or internal systems as MCP endpoints without rewriting them.
  49. 3. **Access Any 3rd-Party API from Chat Applications:** Turn any third-party API into an MCP tool, making it accessible to AI assistants like Claude.
  50. 4. **Minimal Proxy Tools:** Use auto-mcp to proxy APIs that already handle validation and logic—no wrappers needed.
  51. ---
  52. ## 🖥️ Running inside Claude Desktop
  53. Add the following snippet to your **Claude Desktop** configuration (⟂ _Settings → MCP Servers_):
  54. ```jsonc
  55. {
  56. "mcpServers": {
  57. "YourMCP": {
  58. "command": "docker",
  59. "args": [
  60. "run",
  61. "-i",
  62. "--rm",
  63. "-v",
  64. "/Users/you/path/to/swagger.json:/server/swagger.json",
  65. "ghcr.io/brizzai/auto-mcp:latest"
  66. "--swagger-file=/server/swagger.json"
  67. ]
  68. }
  69. },
  70. "globalShortcut": ""
  71. }
  72. ```
  73. Claude will start the container on-demand and connect over STDIO. Replace the host path to `swagger.json` and image tag to suit your setup.
  74. ### CLI flags
  75. - `--mode` – override `server.mode` (`stdio` or `sse`).
  76. - `--swagger-file` – path to the OpenAPI document (default: `swagger.json`).
  77. - `--adjustment-file` - mcp-config-builder output filter/change route descriptions
  78. For detailed configureation guidelines, please see [CONFIGURATION.md](docs/CONFIGURATION.md).
  79. ---
  80. ## 🔐 OAuth Support
  81. Auto MCP supports OAuth 2.1 authentication, including PKCE, dynamic client registration, and multiple providers (internal, GitHub, Google). This allows you to secure your MCP server with industry-standard authentication flows.
  82. See the [OAuth Usage Guide](docs/OAUTH.md) for detailed setup instructions, endpoint descriptions, and testing tips.
  83. ---
  84. ## 🐳 Running with Docker
  85. 1. **Run in local `stdio` mode**:
  86. ```bash
  87. docker run --rm -i \
  88. -v $(pwd)/swagger.json:/server/swagger.json \
  89. ghcr.io/brizzai/auto-mcp:latest \
  90. --swagger-file=/server/swagger.json \
  91. --mode=stdio
  92. ```
  93. 2. **Run in remote `sse`/`http` mode** :
  94. ```bash
  95. docker run \
  96. -v $(pwd)/swagger.json:/server/swagger.json \
  97. ghcr.io/brizzai/auto-mcp:latest \
  98. --swagger-file=/server/swagger.json \
  99. --mode=http
  100. ```
  101. The bundled `docker-compose.yml` maps port 8080 and persists logs to `./logs`.
  102. ### Running the Petshop Example
  103. You can try out the included Petshop demo using Docker. This demo uses a sample configuration and API specs to show how auto-mcp works.
  104. **Steps:**
  105. 1. Make sure you are in the root directory of this repository.
  106. 2. Run the following command:
  107. ```bash
  108. docker run --rm -i \
  109. -v $(pwd)/examples/petshop/config:/config \
  110. ghcr.io/brizzai/auto-mcp:latest
  111. ```
  112. - This command mounts the `examples/petshop/config` directory from your local machine into the Docker container at `/config`.
  113. - The `/config` directory inside the container should contain:
  114. - `config.yaml`: Main configuration file for the demo
  115. - `swagger.json`: API specification for the Petshop service
  116. - `adjustment.yaml`: Optional adjustments or overrides for the API
  117. > **Note:**
  118. > Any files you place in `examples/petshop/config` will overwrite the default `config.yaml`, `swagger.json`, and `adjustment.yaml` inside the container.
  119. This setup allows you to easily test and modify the Petshop demo configuration.
  120. See [docs/CONFIGURATION.md](docs/
  121. CONFIGURATION.md) for all config options
  122. and environment variable overrides.
  123. ## 🤝 Contributing
  124. For detailed contribution guidelines, please see [CONTRIBUTING.md](.github/CONTRIBUTING.md).
  125. ---
  126. ## 📄 License
  127. Distributed under the Apache License 2.0 License. See [`LICENSE`](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.