Skip to content
Back to search

mcp-openapi

OpenAPI specification MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/reapi-com--mcp-openapi/badge.svg)](/listings/reapi-com--mcp-openapi)

HTML

<a href="/listings/reapi-com--mcp-openapi"><img src="/api/listings/reapi-com--mcp-openapi/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 273 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # @reapi/mcp-openapi
  2. A Model Context Protocol (MCP) server that loads and serves multiple OpenAPI specifications to enable LLM-powered IDE integrations. This server acts as a bridge between your OpenAPI specifications and LLM-powered development tools like Cursor and other code editors.
  3. ## Features
  4. - Loads multiple OpenAPI specifications from a directory
  5. - Exposes API operations and schemas through MCP protocol
  6. - Enables LLMs to understand and work with your APIs directly in your IDE
  7. - Supports dereferenced schemas for complete API context
  8. - Maintains a catalog of all available APIs
  9. ## Powered by [ReAPI](https://reapi.com)
  10. This open-source MCP server is sponsored by [ReAPI](https://reapi.com), a next-generation API platform that simplifies API design and testing. While this server provides local OpenAPI integration for development, ReAPI offers two powerful modules:
  11. ### 🎨 API CMS
  12. - Design APIs using an intuitive no-code editor
  13. - Generate and publish OpenAPI specifications automatically
  14. - Collaborate with team members in real-time
  15. - Version control and change management
  16. ### 🧪 API Testing
  17. - The most developer-friendly no-code API testing solution
  18. - Create and manage test cases with an intuitive interface
  19. - Powerful assertion and validation capabilities
  20. - Serverless cloud test executor
  21. - Perfect for both QA teams and developers
  22. - CI/CD integration ready
  23. Try ReAPI for free at [reapi.com](https://reapi.com) and experience the future of API development.
  24. ## Cursor Configuration
  25. To integrate the MCP OpenAPI server with Cursor IDE, you have two options for configuration locations:
  26. ### Option 1: Project-specific Configuration (Recommended)
  27. Create a `.cursor/mcp.json` file in your project directory. This option is recommended as it allows you to maintain different sets of specs for different projects
  28. ```json
  29. {
  30. "mcpServers": {
  31. "@reapi/mcp-openapi": {
  32. "command": "npx",
  33. "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "./specs"],
  34. "env": {}
  35. }
  36. }
  37. }
  38. ```
  39. > **Tip**: Using a relative path like `./specs` makes the configuration portable and easier to share across team members.
  40. >
  41. > **Note**: We recommend using `@latest` tag as we frequently update the server with new features and improvements.
  42. >
  43. > **Important**: Project-specific configuration helps manage LLM context limits. When all specifications are placed in a single folder, the combined metadata could exceed the LLM's context window, leading to errors. Organizing specs by project keeps the context size manageable.
  44. ### Option 2: Global Configuration
  45. Create or edit `~/.cursor/mcp.json` in your home directory to make the server available across all projects:
  46. ```json
  47. {
  48. "mcpServers": {
  49. "@reapi/mcp-openapi": {
  50. "command": "npx",
  51. "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "/path/to/your/specs"],
  52. "env": {}
  53. }
  54. }
  55. }
  56. ```
  57. ### Enable in Cursor Settings
  58. After adding the configuration:
  59. 1. Open Cursor IDE
  60. 2. Go to Settings > Cursor Settings > MCP
  61. 3. Enable the @reapi/mcp-openapi server
  62. 4. Click the refresh icon next to the server to apply changes
  63. > **Note**: By default, Cursor requires confirmation for each MCP tool execution. If you want to allow automatic execution without confirmation, you can enable [Yolo mode](https://docs.cursor.com/context/model-context-protocol#yolo-mode) in Cursor settings.
  64. The server is now ready to use. When you add new OpenAPI specifications to your directory, you can refresh the catalog by:
  65. 1. Opening Cursor's chat panel
  66. 2. Typing one of these prompts:
  67. ```
  68. "Please refresh the API catalog"
  69. "Reload the OpenAPI specifications"
  70. ```
  71. ### OpenAPI Specification Requirements
  72. 1. Place your OpenAPI 3.x specifications in the target directory:
  73. - Supports both JSON and YAML formats
  74. - Files should have `.json`, `.yaml`, or `.yml` extensions
  75. - Scanner will automatically discover and process all specification files
  76. 2. Specification ID Configuration:
  77. - By default, the filename (without extension) is used as the specification ID
  78. - To specify a custom ID, add `x-spec-id` in the OpenAPI info object:
  79. ```yaml
  80. openapi: 3.0.0
  81. info:
  82. title: My API
  83. version: 1.0.0
  84. x-spec-id: my-custom-api-id # Custom specification ID
  85. ```
  86. > **Important**: Setting a custom `x-spec-id` is crucial when working with multiple specifications that have:
  87. > - Similar or identical endpoint paths
  88. > - Same schema names
  89. > - Overlapping operation IDs
  90. >
  91. > The spec ID helps distinguish between these similar resources and prevents naming conflicts. For example:
  92. > ```yaml
  93. > # user-service.yaml
  94. > info:
  95. > x-spec-id: user-service
  96. > paths:
  97. > /users:
  98. > get: ...
  99. >
  100. > # admin-service.yaml
  101. > info:
  102. > x-spec-id: admin-service
  103. > paths:
  104. > /users:
  105. > get: ...
  106. > ```
  107. > Now you can reference these endpoints specifically as `user-service/users` and `admin-service/users`
  108. ## How It Works
  109. 1. The server scans the specified directory for OpenAPI specification files
  110. 2. It processes and dereferences the specifications for complete context
  111. 3. Creates and maintains a catalog of all API operations and schemas
  112. 4. Exposes this information through the MCP protocol
  113. 5. IDE integrations can then use this information to:
  114. - Provide API context to LLMs
  115. - Enable intelligent code completion
  116. - Assist in API integration
  117. - Generate API-aware code snippets
  118. ## Tools
  119. 1. `refresh-api-catalog`
  120. - Refresh the API catalog
  121. - Returns: Success message when catalog is refreshed
  122. 2. `get-api-catalog`
  123. - Get the API catalog, the catalog contains metadata about all openapi specifications, their operations and schemas
  124. - Returns: Complete API catalog with all specifications, operations, and schemas
  125. 3. `search-api-operations`
  126. - Search for operations across specifications
  127. - Inputs:
  128. - `query` (string): Search query
  129. - `specId` (optional string): Specific API specification ID to search within
  130. - Returns: Matching operations from the API catalog
  131. 4. `search-api-schemas`
  132. - Search for schemas across specifications
  133. - Inputs:
  134. - `query` (string): Search query
  135. - `specId` (optional string): Specific API specification ID to search
  136. - Returns: Matching schemas from the API catalog
  137. 5. `load-api-operation-by-operationId`
  138. - Load an operation by operationId
  139. - Inputs:
  140. - `specId` (string): API specification ID
  141. - `operationId` (string): Operation ID to load
  142. - Returns: Complete operation details
  143. 6. `load-api-operation-by-path-and-method`
  144. - Load an operation by path and method
  145. - Inputs:
  146. - `specId` (string): API specification ID
  147. - `path` (string): API endpoint path
  148. - `method` (string): HTTP method
  149. - Returns: Complete operation details
  150. 7. `load-api-schema-by-schemaName`
  151. - Load a schema by schemaName
  152. - Inputs:
  153. - `specId` (string): API specification ID
  154. - `schemaName` (string): Name of the schema to load
  155. - Returns: Complete schema details
  156. ## Roadmap
  157. 1. **Semantic Search**
  158. - Enable natural language queries for API operations and schemas
  159. - Improve search accuracy with semantic understanding
  160. 2. **Remote Specs Sync**
  161. - Support syncing OpenAPI specifications from remote sources
  162. 3. **Code Templates**
  163. - Expose code templates through MCP protocol
  164. - Provide reference patterns for LLM code generation
  165. 4. **Community Contributions**
  166. - Submit feature requests and bug reports
  167. - Contribute to improve the server
  168. ## Example Prompts in Cursor
  169. Here are some example prompts you can use in Cursor IDE to interact with your APIs:
  170. 1. **Explore Available APIs**
  171. ```
  172. "Show me all available APIs in the catalog with their operations"
  173. "List all API specifications and their endpoints"
  174. ```
  175. 2. **API Operation Details**
  176. ```
  177. "Show me the details of the create pet API endpoint"
  178. "What are the required parameters for creating a new pet?"
  179. "Explain the response schema for the pet creation endpoint"
  180. ```
  181. 3. **Schema and Mock Data**
  182. ```
  183. "Generate mock data for the Pet schema"
  184. "Create a valid request payload for the create pet endpoint"
  185. "Show me examples of valid pet objects based on the schema"
  186. ```
  187. 4. **Code Generation**
  188. ```
  189. "Generate an Axios client for the create pet API"
  190. "Create a TypeScript interface for the Pet schema"
  191. "Write a React hook that calls the create pet endpoint"
  192. ```
  193. 5. **API Integration Assistance**
  194. ```
  195. "Help me implement error handling for the pet API endpoints"
  196. "Generate unit tests for the pet API client"
  197. "Create a service class that encapsulates all pet-related API calls"
  198. ```
  199. 6. **Documentation and Usage**
  200. ```
  201. "Show me example usage of the pet API with curl"
  202. "Generate JSDoc comments for the pet API client methods"
  203. "Create a README section explaining the pet API integration"
  204. ```
  205. 7. **Validation and Types**
  206. ```
  207. "Generate Zod validation schema for the Pet model"
  208. "Create TypeScript types for all pet-related API responses"
  209. "Help me implement request payload validation for the pet endpoints"
  210. ```
  211. 8. **API Search and Discovery**
  212. ```
  213. "Find all endpoints related to pet management"
  214. "Show me all APIs that accept file uploads"
  215. "List all endpoints that return paginated responses"
  216. ```
  217. These prompts demonstrate how to leverage the MCP server's capabilities for API development. Feel free to adapt them to your specific needs or combine them for more complex tasks.
  218. ## Contributing
  219. Contributions are welcome! Please feel free to submit a Pull Request.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.