openapiv3-mcp

# Tool List An OpenAPI/Swagger document MCP tool built on [FastMCP](https://gofastmcp.com), providing clean and efficient document querying and analysis capabilities. ## Supported Document Entries - Single OpenAPI 3.x / Swagger 2.0 document, e.g., `/v3/api-docs`, `/v2/api-docs` - Springdoc / Swagger UI multi-service configuration, e.g., `/v3/api-docs/swagger-config` - Springfox Swagger 2.0 grouped resources, e.g., `/swagger-resources` Springfox v2 grouped resources will first read the group list, then load the corresponding document by group name: ```text http://127.0.0.1:10021/makeid-boot/swagger-resources http://127.0.0.1:10021/makeid-boot/v2/api-docs?group=APP ``` ## Installation ```bash git clone <repo-url> cd swagger-mcp pip install -r requirements.txt ``` ## Startup Method 1: HTTP MCP Service HTTP mode requires starting the MCP service of this project first, then let Codex connect to the MCP service address. ### Preload OpenAPI 3 / Springdoc swagger-config ```bash FASTMCP_TRANSPORT=streamable-http \ FASTMCP_HOST=127.0.0.1 \ FASTMCP_PORT=8000 \ python swagger_mcp/server.py \ --swagger-uri http://127.0.0.1:8080/v3/api-docs/swagger-config ``` ### Preload Swagger 2 / Springfox swagger-resources ```bash FASTMCP_TRANSPORT=streamable-http \ FASTMCP_HOST=127.0.0.1 \ FASTMCP_PORT=8000 \ python swagger_mcp/server.py \ --swagger-uri http://127.0.0.1:10021/makeid-boot/swagger-resources \ --swagger-source-type swagger_resources ``` Codex configuration: ```toml [mcp_servers.swagger-mcp] url = "http://127.0.0.1:8000/mcp" ``` ## Startup Method 2: stdio MCP Service stdio mode does not require manually starting the HTTP listener, Codex will start this project according to the configuration. ### OpenAPI 3 / Springdoc swagger-config ```toml [mcp_servers.swagger-mcp] command = "python" args = [ "/Users/huayangchen/mycode/swagger-mcp/server_start.py", "--swagger-uri", "http://127.0.0.1:8080/v3/api-docs/swagger-config", ] ``` ### Swagger 2 / Springfox swagger-resources ```toml [mcp_servers.swagger-mcp] command = "python" args = [ "/Users/huayangchen/mycode/swagger-mcp/server_start.py", "--swagger-uri", "http://127.0.0.1:10021/makeid-boot/swagger-resources", "--swagger-source-type", "swagger_resources", ] ``` ## Usage Process After loading multiple grouped entries, first view the available services, then load a certain group: ```text list_swagger_services load_swagger_service("APP") list_apis get_api_details(path="/xxx", method="GET") ``` If loading a single document, you can directly use `list_apis`, `search_apis`, `get_api_details`, `list_schemas` and other tools. ## Available Tools | Tool Name | Function Description | | --- | --- | | `load_swagger` | Load OpenAPI/Swagger document, swagger-config or swagger-resources | | `list_swagger_services` | List services or groups in swagger-config / swagger-resources | | `load_swagger_service` | Load specific interface document by service name or group name | | `get_swagger_info` | Get basic information of the current document | | `list_apis` | List API endpoints of the current document | | `get_api_details` | Get detailed information of the specified API | | `search_apis` | Search API endpoints | | `list_schemas` | List all data models | | `get_schema_details` | Get detailed information of the specified data model | ## Precautions - The `url` in Codex configuration must be the MCP Server address, e.g., `http://127.0.0.1:8000/mcp`, cannot directly fill in the business Swagger address. - Business Swagger address should be passed through `--swagger-uri`, e.g., `http://127.0.0.1:10021/makeid-boot/swagger-resources`. - Swagger 2 / Springfox's `/swagger-resources` is recommended to add `--swagger-source-type swagger_resources` explicitly, or use `source_type="swagger_resources"` when calling tools. - If using HTTP mode, please confirm that the business service and this MCP service are both started, and the ports are different. - If using stdio mode, please change the path of `server_start.py` to the actual absolute path of your local repository. - Multiple grouped entries will only preload the group list; need to call `load_swagger_service("<group name>")`, then tools like `list_apis` will work for the group document. - Test suggestions run `pytest`, test cases do not depend on external networks. ## Local Development ```bash pytest python swagger_mcp/server.py --help ``` ## License See [LICENSE](./LICENSE).