{"id":24733413,"url":"https://github.com/grll/open-mcp-proxy","last_synced_at":"2025-03-22T16:21:29.829Z","repository":{"id":267520319,"uuid":"901508348","full_name":"grll/open-mcp-proxy","owner":"grll","description":"An open source MCP proxy.","archived":false,"fork":false,"pushed_at":"2025-01-03T17:44:55.000Z","size":159,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-03T18:50:39.887Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/grll.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-12-10T19:38:17.000Z","updated_at":"2025-01-25T19:35:32.000Z","dependencies_parsed_at":"2024-12-10T20:36:17.234Z","dependency_job_id":"59a5b0c0-b67c-4e76-b89c-5425982c583c","html_url":"https://github.com/grll/open-mcp-proxy","commit_stats":null,"previous_names":["grll/open-mcp-proxy","iodmcp/open-mcp-proxy"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grll%2Fopen-mcp-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grll%2Fopen-mcp-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grll%2Fopen-mcp-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grll%2Fopen-mcp-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grll","download_url":"https://codeload.github.com/grll/open-mcp-proxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244983524,"owners_count":20542481,"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":[],"created_at":"2025-01-27T18:15:13.617Z","updated_at":"2025-03-22T16:21:29.807Z","avatar_url":"https://github.com/grll.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Open MCP Proxy\n\nA simple and lightweight open-source bidirectional proxy for MCP servers.\n\nIt exposes several callbacks that you can use to implement your own logic and do your own actions during the MCP protocol lifecycle.\n\nIt supports both SSE and STDIO protocols so it can be used to enable MCP Client supporting only stdio (like the Claude Desktop App) to also support SSE.\n\nIt leverages as much as possible the official mcp-python-sdk to remains simple, lightweight and future-proof.\n\nit declines in 2 versions to support both SSE and STDIO protocols:\n\n**SSE Proxy**\n\n```mermaid\ngraph LR\n    STDIN --\u003e|stdio| Proxy[Open MCP Proxy]\n    Proxy --\u003e|SSE| Server[Remote MCP Server]\n```\n\n```mermaid\ngraph RL\n    Server[Remote MCP Server] --\u003e|SSE| Proxy[Open MCP Proxy]\n    Proxy --\u003e|stdio| STDOUT\n```\n\n**STDIO Proxy**\n\n```mermaid\ngraph LR\n    STDIN --\u003e|stdio| Proxy[Open MCP Proxy]\n    Proxy --\u003e|stdio| Server[Local MCP Server]\n```\n\n```mermaid\ngraph RL\n    Server[Local MCP Server] --\u003e|stdio| Proxy[Open MCP Proxy]\n    Proxy --\u003e|stdio| STDOUT\n```\n\nNote that in both cases the proxy listen to STDIN and write to STDOUT to work seemlessly with stdio MCP Clients.\n\n## Usage\n\n### Hook into the MCP protocol lifecycle\n\nThe recommended approach to hook into the MCP protocol lifecycle is to subclass one of the Proxy class that we expose and override the callback methods you need.\n\nAt the moment, we expose 4 callback methods:\n\n| Method | Description | Parameters |\n|--------|-------------|------------|\n| `_on_mcp_client_message` | Can be used to handle messages from the MCP client | `message: JSONRPCMessage` |\n| `_on_mcp_server_message` | Can be used to handle messages from the MCP server | `message: JSONRPCMessage \\| Exception` |\n| `_on_start` | Can be used to handle the start of the proxy | None |\n| `_on_close` | Can be used to handle the close of the proxy | None |\n\nFor example if you need a proxy over the stdio protocol:\n\n```python\nfrom omproxy.proxy import StdioProxy\n\nclass MyStdioProxy(StdioProxy):\n    def _on_start(self):\n        print(\"Starting proxy\", file=sys.stderr)\n\n    def _on_mcp_client_message(self, message: JSONRPCMessage):\n        print(message, file=sys.stderr)\n\n    def _on_mcp_server_message(self, message: JSONRPCMessage | Exception):\n        print(message, file=sys.stderr)\n\n    def _on_close(self):\n        print(\"Closing proxy\", file=sys.stderr)\n\nif __name__ == \"__main__\":\n    proxy = MyStdioProxy()\n    proxy.run(StdioServerParameters(command=\"uv\", args=[\"run\", \"src/example_server.py\"]))\n```\n\n**tip**: dont write to stdout in your callbacks or anywhere really as it will mess with the stdio MCP communication.\n\n### MCP Client supporting only STDIO to your SSE MCP Server\n\nWe provide a simple CLI to start the proxy if you have an SSE MCP server running and you want to make it available to an MCP Client supporting only stdio you can simply do:\n\n```bash\nuvx omproxy@latest sse --url https://yourssemcpserver.io\n```\n\nsee `uvx omproxy@latest sse --help` for more information including setting headers for authorization for example.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrll%2Fopen-mcp-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrll%2Fopen-mcp-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrll%2Fopen-mcp-proxy/lists"}