{"id":50291611,"url":"https://github.com/openapi/mcp-server","last_synced_at":"2026-05-28T06:13:55.939Z","repository":{"id":358038744,"uuid":"1168347662","full_name":"openapi/mcp-server","owner":"openapi","description":"🧠 A powerful, fully featured MCP Server for interacting with AI agents powered by @Openapi®","archived":false,"fork":false,"pushed_at":"2026-05-15T10:22:54.000Z","size":648,"stargazers_count":14,"open_issues_count":31,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T12:26:43.022Z","etag":null,"topics":["ai","ai-agents","anthropic","api-marketplace","automation","certified-api","claude","claude-code","developer-tools","gemini","genai","llm","mcp","mcp-server","openai","openapi","rest-api"],"latest_commit_sha":null,"homepage":"https://console.openapi.com","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/openapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/code-of-conduct.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-27T09:31:55.000Z","updated_at":"2026-05-15T10:22:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/openapi/mcp-server","commit_stats":null,"previous_names":["openapi/mcp-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/openapi/mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fmcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fmcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fmcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fmcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openapi","download_url":"https://codeload.github.com/openapi/mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fmcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33596458,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","ai-agents","anthropic","api-marketplace","automation","certified-api","claude","claude-code","developer-tools","gemini","genai","llm","mcp","mcp-server","openai","openapi","rest-api"],"created_at":"2026-05-28T06:13:51.633Z","updated_at":"2026-05-28T06:13:55.928Z","avatar_url":"https://github.com/openapi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://openapi.com/\"\u003e\n    \u003cimg alt=\"Openapi MCP\" src=\".github/assets/images/repo-header-a4.png\" \u003e\n  \u003c/a\u003e\n\n  \u003ch1\u003e🔐 Openapi® MCP\u003c/h1\u003e\n  \u003ch4\u003eThe official Python MCP SDK and ready-to-run MCP server for \u003ca href=\"https://openapi.com/\"\u003eOpenapi®\u003c/a\u003e\u003c/h4\u003e\n\n[![build](https://github.com/openapi/mcp-server/actions/workflows/build.yml/badge.svg)](https://github.com/openapi/mcp-server/actions/workflows/build.yml)\n[![PyPI](https://img.shields.io/pypi/v/openapi-mcp-sdk.svg)](https://pypi.org/project/openapi-mcp-sdk/)\n[![Python](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/)\n[![License](https://img.shields.io/github/license/openapi/mcp-server)](LICENSE)\n[![MCP](https://img.shields.io/badge/protocol-MCP-1f6feb.svg)](https://modelcontextprotocol.io/)\n\u003cbr\u003e\n[![Linux Foundation Member](https://img.shields.io/badge/Linux%20Foundation-Silver%20Member-003778?logo=linux-foundation\u0026logoColor=white)](https://www.linuxfoundation.org/about/members)\n\u003c/div\u003e\n\n# Overview\n\nWelcome to **`openapi-mcp-sdk`**, this is the official [openapi.com](https://openapi.com/) MCP SDK.\nIt ships as a Python package on [PyPI](https://pypi.org/project/openapi-mcp-sdk/) and\ncan be used in two ways:\n\n- **Ready-to-use server** — run the MCP gateway directly from the package with a\n  single command, no cloning or setup required.\n- **Python library** — import `openapi_mcp_sdk` in your own project to build a\n  custom MCP server that wraps openapi.com APIs with your own logic, tools, or auth\n  layer on top.\n\n## Environment variables\n\nAll configuration is done through environment variables. None are required to\nstart the server — defaults are suitable for local use.\n\n### Core\n\n| Variable | Default | Description                                                                              |\n|---|---|------------------------------------------------------------------------------------------|\n| `MCP_PORT` | `8080` | HTTP port the server listens on                                                          |\n| `MCP_ENV` | `production` | Runtime environment: `dev` \\| `staging` \\| `production`                                  |\n| `MCP_BASE_URL` | `http://localhost:8080` | Public URL of this server (used to build callback and file download URLs)                |\n| `MCP_CALLBACK_URL` | `$MCP_BASE_URL/callbacks` | Explicit callback URL sent to async APIs                                                 |\n| `MCP_OPENAPI_ENV` | _(empty)_ | Openapi environment: `dev`, `test`, `sandbox` (alias of `test`), or empty for production |\n\n### Storage\n\nThe server needs to store files for APIs that return binary documents (e.g.\ncompany official documents). The storage backend is configurable:\n\n| Variable              | Default | Description |\n|-----------------------|---|---|\n| `MCP_STORAGE_BACKEND` | `local` | `local` \\| `gcs` \\| `s3` |\n| `MCP_STORAGE_PATH`    | `./openapi_storage` | Local path for `local` backend |\n| `MCP_STORAGE_BUCKET`  | _(required for cloud)_ | Bucket name for `gcs` or `s3` |\n| `MCP_STORAGE_REGION`  | _(required for s3)_ | AWS region for the S3 bucket |\n\n### Cache\n\nUsed to share async callback results across multiple server instances.\n\n| Variable            | Default | Description |\n|---------------------|---|---|\n| `MCP_CACHE_BACKEND` | `none` | `none` (in-process dict) \\| `memcached` \\| `redis` |\n| `MCP_CACHE_URL`     | _(none)_ | Redis connection URL (`MCP_CACHE_BACKEND=redis`), e.g. `redis://host:6379` |\n| `MCP_CACHE_HOST`    | _(none)_ | Memcached host (`MCP_CACHE_BACKEND=memcached`) |\n| `MCP_CACHE_PORT`    | `11211` | Memcached port |\n\nSee [`docs/env/`](docs/env/) for per-environment configuration guides (local,\nDocker, AWS, GCP, Kubernetes).\n\n## Features\n\n- **Secure proxy**: Pass-through of the Bearer Token provided by the client, without direct handling of sensitive credentials.\n- **Extensible**: Easily add new tools/APIs by creating modules in [`/apis/`](src/openapi_mcp_sdk/apis/).\n- **MCP-compatible**: Designed according to MCP protocol best practices.\n- **Modular**: All API call logic and tool registration is centralized in [`mcp_core.py`](src/openapi_mcp_sdk/mcp_core.py).\n\n## Quick Start — run from PyPI (recommended)\n\nNo cloning, no virtual environment. Start the server in one command:\n\n```bash\nuvx openapi-mcp-sdk server\n```\n\nThe server starts immediately at `http://localhost:8080`.\n\n### Other runtimes\n\n```bash\n# pipx (ephemeral run, no install needed — similar to uvx)\npipx run openapi-mcp-sdk server\n\n# pip (installs the package, then run the command)\npip install openapi-mcp-sdk \u0026\u0026 openapi-mcp-sdk server\n\n# pip3 on systems where python3 is the default\npip3 install openapi-mcp-sdk \u0026\u0026 openapi-mcp-sdk server\n```\n\n### CLI reference\n\n```\nopenapi-mcp-sdk \u003ccommand\u003e\n\nCommands:\n  server   Start the MCP server (HTTP/SSE, default port 8080)\n  ping     Ping the openapi.com APIs and report latency       [coming soon]\n  token    Generate or inspect an openapi.com Bearer token    [coming soon]\n```\n\n\n\n## Running with Docker\n\nThe project ships a single [`compose.yml`](compose.yml) with the `mcp` service.\n\n```bash\n# Build and start (production-like image)\ndocker compose up --build\n\n# Run in background\ndocker compose up --build -d\n\n# Follow logs\ndocker compose logs -f mcp\n```\n\nThe server will be accessible at `http://localhost:8080`.\n\n\n\n## Debug and Development\n\n### Local development (without Docker)\n\nThe fastest iteration loop runs the server directly with `uvicorn`:\n\n```bash\nmake start\n```\n\nThis sets `PYTHONPATH=src` and starts `uvicorn` with auto-reload disabled. The\nserver listens on `http://0.0.0.0:8080`.\n\nTo test endpoints manually:\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_TOKEN\" http://localhost:8080\n```\n\nThe server prints request headers and parameters to stdout — no extra\nconfiguration needed.\n\n\n\n### Remote debugging with VS Code and Docker (one click)\n\nThe repository is pre-configured for a **single-click** debug experience.\nNo manual steps, no editing compose files, no terminal commands.\n\n#### How it works\n\n| File | Role |\n|---|---|\n| [`docker/dev/Dockerfile`](docker/dev/Dockerfile) | Debug image — adds `debugpy`, exposes port 5678 |\n| [`compose.yml`](compose.yml) | Compose config — dev image, debug ports, bind mount |\n| [`.vscode/tasks.json`](.vscode/tasks.json) | VS Code tasks — starts/stops the container automatically |\n| [`.vscode/launch.json`](.vscode/launch.json) | Launch config — ties everything together under F5 |\n\n#### Workflow\n\n1. **Set your breakpoints** anywhere in `src/`.\n2. **Open Run and Debug** (`Ctrl+Shift+D` / `⌘+Shift+D`).\n3. **Select `MCP: Debug (Docker)`** from the dropdown.\n4. **Press F5.**\n\nVS Code will:\n\n- Build the debug image (`docker/dev/Dockerfile`) if needed.\n- Start the container via `compose.yml` (debug image + bind mount).\n- Wait automatically until `debugpy` is accepting connections on port 5678.\n- Attach `debugpy` — your breakpoints are now live.\n\nWhen you press **⇧F5** (Stop), VS Code detaches and tears down the container.\n\n\u003e **Keep the container alive after detaching?**\n\u003e Remove the `\"postDebugTask\"` line from `.vscode/launch.json`. You can then\n\u003e re-attach at any time by pressing F5 again without rebuilding.\n\n#### Live code reload\n\n`compose.yml` bind-mounts `./src` into `/app/src` inside the container.\nEdits to files under `src/` are reflected **immediately** — no image rebuild\nrequired. Just send a new request and the updated code runs.\n\n#### Path mapping reference\n\n| | Host | Container |\n|---|---|---|\n| Source code | `./src` | `/app/src` |\n| MCP server | `localhost:8080` | `0.0.0.0:8080` |\n| debugpy listener | `localhost:5678` | `0.0.0.0:5678` |\n\n\n\n## Authentication\n\nThe server accepts the Bearer token in two ways:\n\n### Option A — Authorization header (recommended)\n\nPass the token as a standard HTTP header:\n\n```\nAuthorization: Bearer YOUR_TOKEN\n```\n\n### Option B — `?token=` query parameter\n\nSome MCP clients or environments do not support custom HTTP headers. In that\ncase the token can be embedded directly in the server URL as a query parameter:\n\n```\nhttp://YOUR_SERVER_IP:8080/?token=YOUR_TOKEN\n```\n\nThe server automatically promotes it to an `Authorization: Bearer` header\nbefore the request reaches the MCP layer, so the behaviour is identical.\n\n\u003e **When to use `?token=`:** Claude Desktop (as of mid-2025), some browser-based\n\u003e MCP playgrounds, and any client whose configuration only accepts a plain URL\n\u003e without a headers field.\n\n\n\n## MCP Client Configuration (VS Code)\n\n1. **Generate a Bearer Token**\n   From the portal https://console.openapi.com/oauth, create a token with the required scopes.\n\n2. **Create the `.vscode/mcp.json` file**\n\n   **With header (recommended):**\n   ```json\n   {\n     \"servers\": {\n       \"openapi.com\": {\n         \"type\": \"http\",\n         \"url\": \"http://YOUR_SERVER_IP:8080/\",\n         \"headers\": {\n           \"Authorization\": \"Bearer YOUR_TOKEN\"\n         }\n       }\n     }\n   }\n   ```\n\n   **With `?token=` query parameter** (for clients that do not support custom headers):\n   ```json\n   {\n     \"servers\": {\n       \"openapi.com\": {\n         \"type\": \"http\",\n         \"url\": \"http://YOUR_SERVER_IP:8080/?token=YOUR_TOKEN\"\n       }\n     }\n   }\n   ```\n\n3. **Test the integration**\n   - Reload VS Code.\n   - Open the Copilot chat and type `@workspace`.\n   - Use the tools exposed by the MCP server.\n\n\n\n## File storage\n\nSome openapi.com APIs (e.g. **visure camerali** — Italian official company documents)\nreturn large binary files (ZIP archives, PDFs) that cannot be embedded inline in the\nMCP stream. The server downloads these files, stores them, and serves them via a\nseparate HTTP endpoint (`GET /status/{id}/files/{filename}`).\n\n### Default: local filesystem\n\nBy default (`MCP_STORAGE_BACKEND=local`) files are written to `./openapi_storage`\nrelative to the directory from which the server is started:\n\n```\n./openapi_storage/\n└── \u003crequest_id\u003e/\n    ├── document.pdf\n    └── attachments.zip\n```\n\nOverride the path with the `MCP_STORAGE_PATH` environment variable:\n\n```bash\nexport MCP_STORAGE_PATH=/var/data/openapi_storage\nuvx openapi-mcp-sdk server\n```\n\n\u003e The directory is created automatically on first use. For the download links to\n\u003e work correctly, `MCP_BASE_URL` must point to the public address of the server\n\u003e (default: `http://localhost:8080`).\n\n### Cloud storage backends\n\n| `MCP_STORAGE_BACKEND` | Additional variables | Notes |\n|---|---|---|\n| `local` | `MCP_STORAGE_PATH` (default `./openapi_storage`) | Default — local disk or mounted volume |\n| `gcs` | `MCP_STORAGE_BUCKET` | Google Cloud Storage |\n| `s3` | `MCP_STORAGE_BUCKET`, `MCP_STORAGE_REGION` | AWS S3 or any S3-compatible service |\n\nSee [`docs/env/`](docs/env/) for full per-environment configuration guides.\n\n\n\n## Deployment environments\n\n| Environment | Guide |\n|---|---|\n| Local machine (default) | [`docs/env/local.md`](docs/env/local.md) |\n| Docker / Docker Compose | [`docs/env/docker.md`](docs/env/docker.md) |\n| Google Cloud Platform | [`docs/env/gcp.md`](docs/env/gcp.md) |\n| Amazon Web Services | [`docs/env/aws.md`](docs/env/aws.md) |\n| Kubernetes | [`docs/env/kubernetes.md`](docs/env/kubernetes.md) |\n\n\n\n## Project Structure\n\n- [`src/openapi_mcp_sdk/main.py`](src/openapi_mcp_sdk/main.py): FastAPI + MCP server entry point.\n- [`src/openapi_mcp_sdk/mcp_core.py`](src/openapi_mcp_sdk/mcp_core.py): MCP initialization, API call helpers, error handling.\n- [`src/openapi_mcp_sdk/apis/`](src/openapi_mcp_sdk/apis/): Python modules defining MCP tools (one per API/scope).\n- [`requirements.txt`](requirements.txt): Python dependencies.\n- [`compose.yml`](compose.yml): Docker Compose (production image by default; see comments to switch to debug).\n- [`docker/latest/Dockerfile`](docker/latest/Dockerfile): Production Docker image.\n- [`docker/dev/Dockerfile`](docker/dev/Dockerfile): Development image with `debugpy` for VS Code remote debugging.\n- [`.vscode/launch.json`](.vscode/launch.json): VS Code debug configuration (attach to debugpy).\n- [`docs/`](docs/): Documentation and example configurations.\n\n\n\n## Adding New Tools/APIs\n\n1. Create or modify a file in [`/apis/`](apis/), following this pattern:\n   ```python\n   from fastmcp import Context\n   from typing import Any\n   from mcp_core import make_api_call, mcp\n\n   @mcp.tool\n   async def tool_name(parameters..., ctx: Context) -\u003e Any:\n       # ...logic...\n       return make_api_call(ctx, \"GET\", url, params=params)\n   ```\n2. Restart the server to apply the changes.\n\n\n\n## Security Notes\n\n- **Never** hardcode credentials or tokens in the code.\n- The server expects the Bearer Token to be provided by the client via HTTP headers.\n- All API calls are proxied using the token provided by the client.\n\n\n\n## Useful Resources\n\n- [MCP Documentation](https://github.com/anthropics/model-context-protocol)\n- [fastmcp](https://pypi.org/project/fastmcp/)\n- [openapi.com](https://openapi.com/)\n\n\n## Contributing\n\nContributions are always welcome! Whether you want to report bugs, suggest new features, improve documentation, or contribute code, your help is appreciated.\n\nSee [docs/contributing.md](docs/contributing.md) for detailed instructions on how to get started. Please make sure to follow this project's [docs/code-of-conduct.md](docs/code-of-conduct.md) to help maintain a welcoming and collaborative environment.\n\n## Authors\n\nMeet the project authors:\n\n- Simone Desantis ([@SimoneDesantis](https://github.com/SimoneDesantis))\n- Marco Prosperi ([@MarcoProsperi](https://github.com/MarcoProsperi))\n- Francesco Bianco ([@francescobianco](https://github.com/frabcescobianco))\n- Openapi Team ([@openapi-it](https://github.com/openapi-it))\n\n## Partners\n\nMeet our partners using Openapi or contributing to this SDK:\n\n- [Blank](https://www.blank.app/)\n- [Credit Safe](https://www.creditsafe.com/)\n- [Deliveroo](https://deliveroo.it/)\n- [Gruppo MOL](https://molgroupitaly.it/it/)\n- [Jakala](https://www.jakala.com/)\n- [Octotelematics](https://www.octotelematics.com/)\n- [OTOQI](https://otoqi.com/)\n- [PWC](https://www.pwc.com/)\n- [QOMODO S.R.L.](https://www.qomodo.me/)\n- [SOUNDREEF S.P.A.](https://www.soundreef.com/)\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\nThe MIT License is a permissive open-source license that allows you to freely use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, provided that the original copyright notice and this permission notice are included in all copies or substantial portions of the software.\n\nIn short, you are free to use this SDK in your personal, academic, or commercial projects, with minimal restrictions. The project is provided \"as-is\", without any warranty of any kind, either expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement.\n\nFor more details, see the full license text at the [MIT License page](https://choosealicense.com/licenses/mit/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi%2Fmcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenapi%2Fmcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi%2Fmcp-server/lists"}