Skip to content
Back to search

mcpo

A simple, secure MCP-to-OpenAPI proxy 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/open-webui--mcpo/badge.svg)](/listings/open-webui--mcpo)

HTML

<a href="/listings/open-webui--mcpo"><img src="/api/listings/open-webui--mcpo/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 · 276 lines

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

  1. # ⚡️ mcpo
  2. Expose any MCP tool as an OpenAPI-compatible HTTP server—instantly.
  3. mcpo is a dead-simple proxy that takes an MCP server command and makes it accessible via standard RESTful OpenAPI, so your tools "just work" with LLM agents and apps expecting OpenAPI servers.
  4. No custom protocol. No glue code. No hassle.
  5. ## 🤔 Why Use mcpo Instead of Native MCP?
  6. MCP servers usually speak over raw stdio, which is:
  7. - 🔓 Inherently insecure
  8. - ❌ Incompatible with most tools
  9. - 🧩 Missing standard features like docs, auth, error handling, etc.
  10. mcpo solves all of that—without extra effort:
  11. - ✅ Works instantly with OpenAPI tools, SDKs, and UIs
  12. - 🛡 Adds security, stability, and scalability using trusted web standards
  13. - 🧠 Auto-generates interactive docs for every tool, no config needed
  14. - 🔌 Uses pure HTTP—no sockets, no glue code, no surprises
  15. What feels like "one more step" is really fewer steps with better outcomes.
  16. mcpo makes your AI tools usable, secure, and interoperable—right now, with zero hassle.
  17. ## 🚀 Quick Usage
  18. We recommend using uv for lightning-fast startup and zero config.
  19. ```bash
  20. uvx mcpo --port 8000 --api-key "top-secret" -- your_mcp_server_command
  21. ```
  22. Or, if you’re using Python:
  23. ```bash
  24. pip install mcpo
  25. mcpo --port 8000 --api-key "top-secret" -- your_mcp_server_command
  26. ```
  27. To use an SSE-compatible MCP server, simply specify the server type and endpoint:
  28. ```bash
  29. mcpo --port 8000 --api-key "top-secret" --server-type "sse" -- http://127.0.0.1:8001/sse
  30. ```
  31. You can also provide headers for the SSE connection:
  32. ```bash
  33. mcpo --port 8000 --api-key "top-secret" --server-type "sse" --header '{"Authorization": "Bearer token", "X-Custom-Header": "value"}' -- http://127.0.0.1:8001/sse
  34. ```
  35. To use a Streamable HTTP-compatible MCP server, specify the server type and endpoint:
  36. ```bash
  37. mcpo --port 8000 --api-key "top-secret" --server-type "streamable-http" -- http://127.0.0.1:8002/mcp
  38. ```
  39. You can also run mcpo via Docker with no installation:
  40. ```bash
  41. docker run -p 8000:8000 ghcr.io/open-webui/mcpo:main --api-key "top-secret" -- your_mcp_server_command
  42. ```
  43. Example:
  44. ```bash
  45. uvx mcpo --port 8000 --api-key "top-secret" -- uvx mcp-server-time --local-timezone=America/New_York
  46. ```
  47. That’s it. Your MCP tool is now available at http://localhost:8000 with a generated OpenAPI schema — test it live at [http://localhost:8000/docs](http://localhost:8000/docs).
  48. 🤝 **To integrate with Open WebUI after launching the server, check our [docs](https://docs.openwebui.com/openapi-servers/open-webui/).**
  49. ### 🌐 Serving Under a Subpath (`--root-path`)
  50. If you need to serve mcpo behind a reverse proxy or under a subpath (e.g., `/api/mcpo`), use the `--root-path` argument:
  51. ```bash
  52. mcpo --port 8000 --root-path "/api/mcpo" --api-key "top-secret" -- your_mcp_server_command
  53. ```
  54. All routes will be served under the specified root path, e.g. `http://localhost:8000/api/mcpo/memory`.
  55. ### 🔄 Using a Config File
  56. You can serve multiple MCP tools via a single config file that follows the [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) format.
  57. Enable hot-reload mode with `--hot-reload` to automatically watch your config file for changes and reload servers without downtime:
  58. Start via:
  59. ```bash
  60. mcpo --config /path/to/config.json
  61. ```
  62. Or with hot-reload enabled:
  63. ```bash
  64. mcpo --config /path/to/config.json --hot-reload
  65. ```
  66. Example config.json:
  67. ```json
  68. {
  69. "mcpServers": {
  70. "memory": {
  71. "command": "npx",
  72. "args": ["-y", "@modelcontextprotocol/server-memory"]
  73. },
  74. "time": {
  75. "command": "uvx",
  76. "args": ["mcp-server-time", "--local-timezone=America/New_York"],
  77. "disabledTools": ["convert_time"] // Disable specific tools if needed
  78. },
  79. "mcp_sse": {
  80. "type": "sse", // Explicitly define type
  81. "url": "http://127.0.0.1:8001/sse",
  82. "headers": {
  83. "Authorization": "Bearer token",
  84. "X-Custom-Header": "value"
  85. }
  86. },
  87. "mcp_streamable_http": {
  88. "type": "streamable-http",
  89. "url": "http://127.0.0.1:8002/mcp"
  90. } // Streamable HTTP MCP Server
  91. }
  92. }
  93. ```
  94. Each tool will be accessible under its own unique route, e.g.:
  95. - http://localhost:8000/memory
  96. - http://localhost:8000/time
  97. Each with a dedicated OpenAPI schema and proxy handler. Access full schema UI at: `http://localhost:8000/<tool>/docs` (e.g. /memory/docs, /time/docs)
  98. ### 🔐 OAuth 2.1 Authentication
  99. mcpo supports OAuth 2.1 authentication for MCP servers that require it. The implementation defaults to **dynamic client registration**, so most servers only need minimal configuration:
  100. ```json
  101. {
  102. "mcpServers": {
  103. "oauth-protected-server": {
  104. "type": "streamable-http",
  105. "url": "http://localhost:8000/mcp",
  106. "oauth": {
  107. "server_url": "http://localhost:8000"
  108. }
  109. }
  110. }
  111. }
  112. ```
  113. #### OAuth Configuration Options
  114. **Basic Options:**
  115. - `server_url` (required): OAuth server base URL
  116. - `storage_type`: "file" (persistent) or "memory" (session-only, default: "file")
  117. - `callback_port`: Local port for OAuth callback (default: 3030)
  118. - `use_loopback`: Auto-open browser for auth (default: true)
  119. **Advanced Options (rarely needed):**
  120. For servers that don't support dynamic client registration, you can specify static client metadata:
  121. ```json
  122. {
  123. "mcpServers": {
  124. "legacy-oauth-server": {
  125. "type": "streamable-http",
  126. "url": "http://api.example.com/mcp",
  127. "oauth": {
  128. "server_url": "http://api.example.com",
  129. "client_metadata": {
  130. "client_name": "My MCPO Client",
  131. "redirect_uris": ["http://localhost:3030/callback"]
  132. }
  133. }
  134. }
  135. }
  136. }
  137. ```
  138. > **Note**: Avoid setting `scope`, `authorization_endpoint`, or `token_endpoint` in the config. These are automatically discovered from the server's OAuth metadata during the dynamic registration flow.
  139. On first connection, mcpo will:
  140. 1. Perform dynamic client registration (if supported)
  141. 2. Open your browser for authorization
  142. 3. Capture the OAuth callback automatically
  143. 4. Store tokens securely (in `~/.mcpo/tokens/` for file storage)
  144. 5. Use tokens for all subsequent requests
  145. OAuth is supported for `streamable-http` server types. See [OAUTH_GUIDE.md](OAUTH_GUIDE.md) for detailed documentation.
  146. ## 🔧 Requirements
  147. - Python 3.8+
  148. - uv (optional, but highly recommended for performance + packaging)
  149. ## 🛠️ Development & Testing
  150. To contribute or run tests locally:
  151. 1. **Set up the environment:**
  152. ```bash
  153. # Clone the repository
  154. git clone https://github.com/open-webui/mcpo.git
  155. cd mcpo
  156. # Install dependencies (including dev dependencies)
  157. uv sync --dev
  158. ```
  159. 2. **Run tests:**
  160. ```bash
  161. uv run pytest
  162. ```
  163. 3. **Running Locally with Active Changes:**
  164. To run `mcpo` with your local modifications from a specific branch (e.g., `my-feature-branch`):
  165. ```bash
  166. # Ensure you are on your development branch
  167. git checkout my-feature-branch
  168. # Make your code changes in the src/mcpo directory or elsewhere
  169. # Run mcpo using uv, which will use your local, modified code
  170. # This command starts mcpo on port 8000 and proxies your_mcp_server_command
  171. uv run mcpo --port 8000 -- your_mcp_server_command
  172. # Example with a test MCP server (like mcp-server-time):
  173. # uv run mcpo --port 8000 -- uvx mcp-server-time --local-timezone=America/New_York
  174. ```
  175. This allows you to test your changes interactively before committing or creating a pull request. Access your locally running `mcpo` instance at `http://localhost:8000` and the auto-generated docs at `http://localhost:8000/docs`.
  176. ## 🪪 License
  177. MIT
  178. ## 🤝 Contributing
  179. We welcome and strongly encourage contributions from the community!
  180. Whether you're fixing a bug, adding features, improving documentation, or just sharing ideas—your input is incredibly valuable and helps make mcpo better for everyone.
  181. Getting started is easy:
  182. - Fork the repo
  183. - Create a new branch
  184. - Make your changes
  185. - Open a pull request
  186. Not sure where to start? Feel free to open an issue or ask a question—we’re happy to help you find a good first task.
  187. ## ✨ Star History
  188. <a href="https://star-history.com/#open-webui/mcpo&Date">
  189. <picture>
  190. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=open-webui/mcpo&type=Date&theme=dark" />
  191. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=open-webui/mcpo&type=Date" />
  192. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=open-webui/mcpo&type=Date" />
  193. </picture>
  194. </a>
  195. ---
  196. ✨ Let's build the future of interoperable AI tooling together!

Ratings and comments

Sign in to rate this skill.

Sign in

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