{"id":22889317,"url":"https://github.com/SecretiveShell/MCP-Bridge","last_synced_at":"2025-08-11T22:32:46.067Z","repository":{"id":265779125,"uuid":"896594784","full_name":"SecretiveShell/MCP-Bridge","owner":"SecretiveShell","description":"A middleware to provide an openAI compatible endpoint that can call MCP tools","archived":false,"fork":false,"pushed_at":"2024-12-11T12:06:41.000Z","size":83,"stargazers_count":22,"open_issues_count":3,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-11T12:23:23.304Z","etag":null,"topics":["ai","claude","mcp","mcp-server","mcp-servers","model-context-protocol","openai","openai-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SecretiveShell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-30T19:29:35.000Z","updated_at":"2024-12-11T06:38:47.000Z","dependencies_parsed_at":"2024-11-30T22:40:49.262Z","dependency_job_id":"ed211d65-ce48-43da-b7fd-0dbbd2eb755e","html_url":"https://github.com/SecretiveShell/MCP-Bridge","commit_stats":null,"previous_names":["secretiveshell/mcp-bridge"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SecretiveShell%2FMCP-Bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SecretiveShell%2FMCP-Bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SecretiveShell%2FMCP-Bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SecretiveShell%2FMCP-Bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SecretiveShell","download_url":"https://codeload.github.com/SecretiveShell/MCP-Bridge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229619207,"owners_count":18099878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","mcp","mcp-server","mcp-servers","model-context-protocol","openai","openai-api"],"created_at":"2024-12-13T21:28:09.182Z","updated_at":"2025-08-11T22:32:46.055Z","avatar_url":"https://github.com/SecretiveShell.png","language":"Python","readme":"# MCP-Bridge\n\n\u003cp\u003e\n  \u003ca href=\"https://discord.gg/4NVQHqNxSZ\"\u003e\u003cimg alt=\"Discord\" src=\"https://img.shields.io/discord/1320517159331430480?style=flat\u0026logo=discord\u0026color=blue\"\u003e\u003c/a\u003e\n  \u003ca href=\"/docs/README.md\"\u003e\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/docs-md-blue\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/License-MIT-blue?style=flat\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\nMCP-Bridge acts as a bridge between the OpenAI API and MCP (MCP) tools, allowing developers to leverage MCP tools through the OpenAI API interface.\n\n\u003e [!NOTE]\n\u003e \n\u003e  Looking for new maintainers to assist with the project. Reach out in the Discord or open an issue if you are interested.\n\n## Overview\nMCP-Bridge is designed to facilitate the integration of MCP tools with the OpenAI API. It provides a set of endpoints that can be used to interact with MCP tools in a way that is compatible with the OpenAI API. This allows you to use any client with any MCP tool without explicit support for MCP. For example, see this example of using Open Web UI with the official MCP fetch tool. \n\n![open web ui example](/assets/owui_example.png)\n\n## Current Features\n\nworking features:\n\n- non streaming chat completions with MCP\n- streaming chat completions with MCP\n\n- non streaming completions without MCP\n\n- MCP tools\n- MCP sampling\n\n- SSE Bridge for external clients\n\nplanned features:\n\n- streaming completions are not implemented yet\n\n- MCP resources are planned to be supported\n\n## Installation\n\nThe recommended way to install MCP-Bridge is to use Docker. See the example compose.yml file for an example of how to set up docker. \n\nNote that this requires an inference engine with tool call support. I have tested this with vLLM with success, though ollama should also be compatible.\n\n### Docker installation\n\n1. **Clone the repository**\n\n2. **Edit the compose.yml file**\n\nYou will need to add a reference to the config.json file in the compose.yml file. Pick any of\n- add the config.json file to the same directory as the compose.yml file and use a volume mount (you will need to add the volume manually)\n- add a http url to the environment variables to download the config.json file from a url\n- add the config json directly as an environment variable\n\nsee below for an example of each option:\n```bash\nenvironment:\n  - MCP_BRIDGE__CONFIG__FILE=config.json # mount the config file for this to work\n  - MCP_BRIDGE__CONFIG__HTTP_URL=http://10.88.100.170:8888/config.json\n  - MCP_BRIDGE__CONFIG__JSON={\"inference_server\":{\"base_url\":\"http://example.com/v1\",\"api_key\":\"None\"},\"mcp_servers\":{\"fetch\":{\"command\":\"uvx\",\"args\":[\"mcp-server-fetch\"]}}}\n```\nThe mount point for using the config file would look like:\n```yaml\n    volumes:\n      - ./config.json:/mcp_bridge/config.json\n```\n\n3. **run the service**\n```\ndocker-compose up --build -d\n```\n\n### Manual installation (no docker)\n\nIf you want to run the application without docker, you will need to install the requirements and run the application manually.\n\n1. **Clone the repository**\n\n2. **Set up a dependencies:**\n```bash\nuv sync\n```\n\n3. **Create a config.json file in the root directory**\n\nHere is an example config.json file:\n```json\n{\n   \"inference_server\": {\n      \"base_url\": \"http://example.com/v1\",\n      \"api_key\": \"None\"\n   },\n   \"mcp_servers\": {\n      \"fetch\": {\n        \"command\": \"uvx\",\n        \"args\": [\"mcp-server-fetch\"]\n      }\n   }\n}\n```\n\n4. **Run the application:**\n```bash\nuv run mcp_bridge/main.py\n```\n\n## Usage\nOnce the application is running, you can interact with it using the OpenAI API.\n\nView the documentation at [http://yourserver:8000/docs](http://localhost:8000/docs). There is an endpoint to list all the MCP tools available on the server, which you can use to test the application configuration.\n\n## Rest API endpoints\n\nMCP-Bridge exposes many rest api endpoints for interacting with all of the native MCP primatives. This lets you outsource the complexity of dealing with MCP servers to MCP-Bridge without comprimising on functionality. See the openapi docs for examples of how to use this functionality.\n\n## SSE Bridge\nMCP-Bridge also provides an SSE bridge for external clients. This lets external chat apps with explicit MCP support use MCP-Bridge as a MCP server. Point your client at the SSE endpoint (http://yourserver:8000/mcp-server/sse) and you should be able to see all the MCP tools available on the server.\n\nThis also makes it easy to test if your configuration is working correctly. You can use [wong2/mcp-cli](https://github.com/wong2/mcp-cli?tab=readme-ov-file#connect-to-a-running-server-over-sse) to test your configuration. `npx @wong2/mcp-cli --sse http://localhost:8000/mcp-server/sse`\n\nIf you want to use the tools inside of [claude desktop](https://claude.ai/download) or other `STDIO` only MCP clients, you can do this with a tool such as [lightconetech/mcp-gateway](https://github.com/lightconetech/mcp-gateway)\n\n## Configuration\n\nTo add new MCP servers, edit the config.json file.\n\n### API Key Authentication\n\nMCP-Bridge supports API key authentication to secure your server. To enable this feature, add something like this to your `config.json` file:\n\n```json\n{\n    \"security\": {\n      \"auth\": {\n        \"enabled\": true,\n        \"api_keys\": [\n          {\n            \"key\": \"your-secure-api-key-here\"\n          }\n        ]\n      }\n    }\n}\n```\n\nWhen making requests to the MCP-Bridge server, include the API key in the Authorization header as a Bearer token:\n\n```\nAuthorization: Bearer your-secure-api-key-here\n```\n\nIf the `api_key` field is empty or not present in the configuration, authentication will be skipped, allowing backward compatibility.\n\n### Full Configuration Example\n\nan example config.json file with most of the options explicitly set:\n\n```json\n{\n    \"inference_server\": {\n        \"base_url\": \"http://localhost:8000/v1\",\n        \"api_key\": \"None\"\n    },\n    \"sampling\": {\n        \"timeout\": 10,\n        \"models\": [\n            {\n                \"model\": \"gpt-4o\",\n                \"intelligence\": 0.8,\n                \"cost\": 0.9,\n                \"speed\": 0.3\n            },\n            {\n                \"model\": \"gpt-4o-mini\",\n                \"intelligence\": 0.4,\n                \"cost\": 0.1,\n                \"speed\": 0.7\n            }\n        ]\n    },\n    \"mcp_servers\": {\n        \"fetch\": {\n            \"command\": \"uvx\",\n            \"args\": [\n                \"mcp-server-fetch\"\n            ]\n        }\n    },\n    \"security\": {\n      \"auth\": {\n        \"enabled\": true,\n        \"api_keys\": [\n          {\n            \"key\": \"your-secure-api-key-here\"\n          }\n        ]\n      }\n    },\n    \"network\": {\n        \"host\": \"0.0.0.0\",\n        \"port\": 9090\n    },\n    \"logging\": {\n        \"log_level\": \"DEBUG\"\n    }\n}\n```\n\n| Section          | Description                        |\n| ---------------- | ---------------------------------- |\n| inference_server | The inference server configuration |\n| mcp_servers      | The MCP servers configuration      |\n| network          | uvicorn network configuration      |\n| logging          | The logging configuration          |\n| api_key          | API key for server authentication  |\n\n## Support\n\nIf you encounter any issues please open an issue or join the [discord](https://discord.gg/4NVQHqNxSZ).\n\nThere is also documentation available [here](/docs/README.md).\n\n## How does it work\n\nThe application sits between the OpenAI API and the inference engine. An incoming request is modified to include tool definitions for all MCP tools available on the MCP servers. The request is then forwarded to the inference engine, which uses the tool definitions to create tool calls. MCP bridge then manage the calls to the tools. The request is then modified to include the tool call results, and is returned to the inference engine again so the LLM can create a response. Finally, the response is returned to the OpenAI API.\n\n```mermaid\nsequenceDiagram\n    participant OpenWebUI as Open Web UI\n    participant MCPProxy as MCP Proxy\n    participant MCPserver as MCP Server\n    participant InferenceEngine as Inference Engine\n\n    OpenWebUI -\u003e\u003e MCPProxy: Request\n    MCPProxy -\u003e\u003e MCPserver: list tools\n    MCPserver -\u003e\u003e MCPProxy: list of tools\n    MCPProxy -\u003e\u003e InferenceEngine: Forward Request\n    InferenceEngine -\u003e\u003e MCPProxy: Response\n    MCPProxy -\u003e\u003e MCPserver: call tool\n    MCPserver -\u003e\u003e MCPProxy: tool response\n    MCPProxy -\u003e\u003e InferenceEngine: llm uses tool response\n    InferenceEngine -\u003e\u003e MCPProxy: Response\n    MCPProxy -\u003e\u003e OpenWebUI: Return Response\n```\n\n## Contribution Guidelines\nContributions to MCP-Bridge are welcome! To contribute, please follow these steps:\n1. Fork the repository.\n2. Create a new branch for your feature or bug fix.\n3. Make your changes and commit them.\n4. Push your changes to your fork.\n5. Create a pull request to the main repository.\n\n## License\nMCP-Bridge is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.\n","funding_links":[],"categories":["MCP Clients","🔌 Integration Tools","Utilities","实用工具","📚 Projects (1974 total)","Clients","🤖 AI/ML","AI Services","クライアント","Python","Containerised MCP Servers","Table of Contents","MCP Servers","📂 카테고리","MCP Servers \u0026 Protocol"],"sub_categories":["Weather","Clients \u0026 Interfaces","Proxies and Gateways","MCP Servers","🎧 \u003ca name=\"text-to-speech\"\u003e\u003c/a\u003eテキスト読み上げ","🛠️ \u003ca name=\"other-tools-and-integrations\"\u003e\u003c/a\u003eOther Tools and Integrations","AI \u0026 Machine Learning","AI Services","Other MCP Servers","🔧 Utilities"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSecretiveShell%2FMCP-Bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSecretiveShell%2FMCP-Bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSecretiveShell%2FMCP-Bridge/lists"}