{"id":30868878,"url":"https://github.com/sotayamashita/openapi-mcp-server","last_synced_at":"2026-06-13T09:02:01.646Z","repository":{"id":287167198,"uuid":"963825806","full_name":"sotayamashita/openapi-mcp-server","owner":"sotayamashita","description":"Powerful bridge between OpenAPI specifications and AI assistants using the Model Context Protocol (MCP). Automatically converts any OpenAPI/Swagger API specification into MCP tools that can be used by AI assistants like Claude Desktop.","archived":false,"fork":false,"pushed_at":"2026-05-21T22:09:17.000Z","size":307,"stargazers_count":7,"open_issues_count":9,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-22T07:39:22.996Z","etag":null,"topics":["ai","api","bridge","cli","llm","mcp","mcp-server","mcp-tools","model-context-protocol","oas","openapi","server","swagger","tool"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/sotayamashita.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-10T09:10:24.000Z","updated_at":"2026-03-27T17:31:32.000Z","dependencies_parsed_at":"2025-05-05T16:37:08.351Z","dependency_job_id":"a01f55da-d1b6-44e3-8b1f-7460e7616555","html_url":"https://github.com/sotayamashita/openapi-mcp-server","commit_stats":null,"previous_names":["sotayamashita/openapi-mcp-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sotayamashita/openapi-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sotayamashita%2Fopenapi-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sotayamashita%2Fopenapi-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sotayamashita%2Fopenapi-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sotayamashita%2Fopenapi-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sotayamashita","download_url":"https://codeload.github.com/sotayamashita/openapi-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sotayamashita%2Fopenapi-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34278154,"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-06-13T02:00:06.617Z","response_time":62,"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","api","bridge","cli","llm","mcp","mcp-server","mcp-tools","model-context-protocol","oas","openapi","server","swagger","tool"],"created_at":"2025-09-07T22:03:56.705Z","updated_at":"2026-06-13T09:02:01.611Z","avatar_url":"https://github.com/sotayamashita.png","language":"TypeScript","funding_links":[],"categories":["AI/ML"],"sub_categories":[],"readme":"# @openapi-mcp/server\n\n[![MCP Server](https://badge.mcpx.dev?type=server \"MCP Server\")](https://modelcontextprotocol.io/introduction) [![npm version](https://badge.fury.io/js/@openapi-mcp%2Fserver.svg?icon=si%3Anpm)](https://badge.fury.io/js/@openapi-mcp%2Fserver) [![Test](https://github.com/sotayamashita/openapi-mcp-server/actions/workflows/test.yml/badge.svg)](https://github.com/sotayamashita/openapi-mcp-server/actions/workflows/test.yml) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nThe openapi-mcp-server is a powerful bridge between OpenAPI specifications and AI assistants using the Model Context Protocol (MCP). It automatically converts any OpenAPI/Swagger API specification into MCP tools that can be used by AI assistants like Claude Desktop. This enables AI assistants to seamlessly interact with your APIs, making them capable of performing real-world actions through your services without requiring custom integrations.\n\n## Features\n\n\u003e **⚠️ Note:**\n\u003e This server **requires** every operation in your OpenAPI/Swagger specification to have an `operationId`. If any operation is missing an `operationId`, the server will fail to start or process the specification. Always ensure that all operations are explicitly assigned a unique and descriptive `operationId`.\n\n- 🔌 **OpenAPI Integration**\n  - Automatically converts OpenAPI/Swagger specifications into MCP tools\n- 📚 **Multiple OpenAPI Versions**\n  - Support for OpenAPI v3.0.0 and v3.1.0\n- 🔐 **Authentication Support**:\n  - HTTP authentication schemes:\n    - Basic authentication\n    - Bearer token authentication (static tokens, e.g., Personal Access Tokens)\n    - Other HTTP schemes as defined by [RFC 7235](https://tools.ietf.org/html/rfc7235)\n  - API keys:\n    - Header-based API keys\n\n## Limitations\n\n⚠️ **Version Support**:\n\n- [ ] OpenAPI v2.0 (Swagger) is not currently supported\n\n⚠️ **Authentication Limitations**:\n\n- [ ] OAuth 2.0 authentication is not supported\n- [ ] OpenID Connect Discovery is not supported\n- [ ] Query parameter-based API keys are not supported\n- [ ] Cookie-based authentication is not supported\n- [ ] Dynamic JWT authentication (login-generated tokens) is not supported\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/sotayamashita/openapi-mcp-server.git\ncd openapi-mcp-server\n\n# Install dependencies\nbun install\n```\n\n## Usage\n\nYou can run the server by providing an OpenAPI specification URL or file path:\n\n```bash\n# Using a local file\nbun run src/index.ts ./path/to/openapi.yml\n\n# Using a URL\nbun run src/index.ts --api https://example.com/api-spec.json\n```\n\n## Configuration\n\n### Environment Variables\n\n- **`BASE_URL`**\n\n  - Required: Yes\n  - Description: API endpoint. [Server Object](https://swagger.io/specification#server-object)'s URL\n\n- **`HEADERS`**\n  - Required: No\n  - Default: `{\"Content-Type\": \"application/json\",\"User-Agent\": \"openapi-mcp-server\"}`\n  - Description: Custom headers that will overwrite default headers\n\n### Claude Desktop Integration\n\nTo use this MCP server with Claude Desktop:\n\n1. Open your Claude Desktop configuration file:\n\n   ```bash\n   # macOS/Linux\n   code ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n   ```\n\n2. Add the following configuration:\n   ```json\n   {\n     \"mcpServer\": {\n       \"openapi-mcp-server\": {\n         \"command\": \"bun\",\n         \"args\": [\n           \"/path/to/openapi-mcp-server/src/index.ts\",\n           \"/path/to/openapi-mcp-server/demo/openapi.yml\"\n         ],\n         \"env\": {\n           \"BASE_URL\": \"https://api.example.com/v1/\",\n           \"HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ****\\\"}\"\n         }\n       }\n     }\n   }\n   ```\n\nFor more detailed instructions, see the [MCP quickstart guide](https://modelcontextprotocol.io/quickstart/user).\n\n### Cursor Integration\n\nTo use this MCP server with Cursor as Global:\n\n1. Open Cursor\n2. Open Cursor Settings \u003e MCP\n3. Click \"+ Add new global MCP Server\"\n4. Add the following configuration:\n   ```json\n   {\n     \"mcpServer\": {\n       \"openapi-mcp-server\": {\n         \"command\": \"bun\",\n         \"args\": [\n           \"/path/to/openapi-mcp-server/src/index.ts\",\n           \"/path/to/openapi-mcp-server/demo/openapi.yml\"\n         ],\n         \"env\": {\n           \"BASE_URL\": \"https://api.example.com/v1/\",\n           \"HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ****\\\"}\"\n         }\n       }\n     }\n   }\n   ```\n\nFor more detailed instructions, see the [Cursor's Model Context Protocol](https://docs.cursor.com/context/model-context-protocol#mcp-resources).\n\n## Best Practices\n\n### OpenAPI/Swagger Specifications\n\n#### Use Descriptive `operationId` Fields\n\nThe `operationId` field in your OpenAPI/Swagger specification plays a crucial role in how tools are presented to AI assistants. When converting your API to MCP tools:\n\n- **Tool Naming**: The `operationId` is used directly as the MCP tool name\n- **Clarity**: Descriptive `operationId` values make it easier for AI assistants to understand and use your API\n- **Consistency**: Use a consistent naming pattern (e.g., `getUser`, `createUser`, `updateUserPassword`)\n\nExample of a well-defined operation:\n\n```yaml\npaths:\n  /users/{userId}:\n    get:\n      operationId: getUserById\n      summary: Retrieve user information\n      description: Returns detailed information about a specific user\n```\n\n#### Include Detailed Operation Descriptions\n\nThe `description` field for each operation is equally important:\n\n- **Tool Selection**: AI assistants use this description to determine which tool is appropriate for a given task\n- **Understanding**: Comprehensive descriptions help the AI understand exactly what the operation does\n- **Context**: Include information about parameters, expected responses, and potential errors\n\nExample of a well-described operation:\n\n```yaml\npaths:\n  /users:\n    post:\n      operationId: createUser\n      summary: Create a new user account\n      description: |\n        Creates a new user in the system. Requires a unique email address and a \n        password that meets security requirements (min 8 chars, including uppercase, \n        lowercase, number). Returns the created user object with an assigned user ID.\n```\n\nWithout thorough descriptions, AI assistants may struggle to identify the right operations for user requests or may use them incorrectly. The quality of your API descriptions directly impacts how effectively AI can leverage your tools.\n\n## Development\n\n### Development Commands\n\n```bash\n# Run tests\nbun vitest run\n\n# Run tests with watch mode\nbun vitest\n\n# Run tests with coverage\nbun vitest run --coverage\n\n# Format code\nbun prettier . --write\n```\n\n### Manual Release Process (Using Release Branch)\n\nThis section outlines the manual steps for creating a new release using a dedicated release branch. This method helps isolate the release process from the `main` branch until publication.\n\n**Prerequisites:**\n\n- All changes intended for the release have been merged into the `main` branch.\n- You are logged into your npm account (`npm login`).\n- Changesets CLI is accessible (this guide uses `bunx`).\n\n**Steps:**\n\n1.  **Ensure `main` is up-to-date:**\n\n    ```bash\n    git checkout main\n    git pull origin main\n    ```\n\n2.  **Create a release branch:** Name it according to the version you intend to release (e.g., `v0.1.0`).\n\n    ```bash\n    git checkout -b release/vX.Y.Z main\n    ```\n\n    Replace `vX.Y.Z` with the target version.\n\n3.  **Bump versions and update Changelog:** This command consumes the changeset files (in `.changeset/`), updates the version in `package.json`, and updates `CHANGELOG.md`.\n\n    ```bash\n    bunx @changesets/cli version\n    ```\n\n    Review the changes applied to `package.json` and `CHANGELOG.md` to ensure they are correct.\n\n4.  **Commit the versioning changes:**\n\n    ```bash\n    git add .\n    git commit -m \"chore: update versions and changelogs for vX.Y.Z\"\n    ```\n\n    Replace `vX.Y.Z` with the target version.\n\n5.  **Build the project:** Ensure the distribution files are generated with the latest changes.\n\n    ```bash\n    bun run build\n    ```\n\n6.  **Publish to npm:** Publish the new version to the npm registry.\n\n    ```bash\n    npm publish\n    ```\n\n    _Ensure your `package.json` includes `\"publishConfig\": { \"access\": \"public\" }` for scoped public packages._\n    _(You might also use `bun publish`, but confirm its behavior with scoped public packages if you choose this.)_\n\n7.  **Tag the release in Git:** Create a Git tag that matches the version published to npm.\n\n    ```bash\n    # Replace X.Y.Z with the actual version number, e.g., 0.1.0\n    git tag @openapi-mcp/server@X.Y.Z\n    ```\n\n8.  **Merge the release branch back into `main`:** This brings the version bump and CHANGELOG updates into your main branch.\n\n    ```bash\n    git checkout main\n    git merge --no-ff release/vX.Y.Z\n    ```\n\n    _(Using `--no-ff` creates a merge commit, which can help in tracking releases in the Git history)._\n\n9.  **Push `main` and the new tag to the remote repository:**\n\n    ```bash\n    git push origin main --tags\n    ```\n\n10. **(Optional) Clean up:** Delete the release branch locally and remotely if it's no longer needed.\n    ```bash\n    git branch -d release/vX.Y.Z\n    git push origin --delete release/vX.Y.Z\n    ```\n\nFor more detailed information on using Changesets, refer to the [official Changesets documentation](https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsotayamashita%2Fopenapi-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsotayamashita%2Fopenapi-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsotayamashita%2Fopenapi-mcp-server/lists"}