Back to search
mcp-openapi
MCP serverGitHub
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
Markdown
[](/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)
- # @reapi/mcp-openapi
- 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.
- ## Features
- - Loads multiple OpenAPI specifications from a directory
- - Exposes API operations and schemas through MCP protocol
- - Enables LLMs to understand and work with your APIs directly in your IDE
- - Supports dereferenced schemas for complete API context
- - Maintains a catalog of all available APIs
- ## Powered by [ReAPI](https://reapi.com)
- 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:
- ### 🎨 API CMS
- - Design APIs using an intuitive no-code editor
- - Generate and publish OpenAPI specifications automatically
- - Collaborate with team members in real-time
- - Version control and change management
- ### 🧪 API Testing
- - The most developer-friendly no-code API testing solution
- - Create and manage test cases with an intuitive interface
- - Powerful assertion and validation capabilities
- - Serverless cloud test executor
- - Perfect for both QA teams and developers
- - CI/CD integration ready
- Try ReAPI for free at [reapi.com](https://reapi.com) and experience the future of API development.
- ## Cursor Configuration
- To integrate the MCP OpenAPI server with Cursor IDE, you have two options for configuration locations:
- ### Option 1: Project-specific Configuration (Recommended)
- 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
- ```json
- {
- "mcpServers": {
- "@reapi/mcp-openapi": {
- "command": "npx",
- "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "./specs"],
- "env": {}
- }
- }
- }
- ```
- > **Tip**: Using a relative path like `./specs` makes the configuration portable and easier to share across team members.
- >
- > **Note**: We recommend using `@latest` tag as we frequently update the server with new features and improvements.
- >
- > **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.
- ### Option 2: Global Configuration
- Create or edit `~/.cursor/mcp.json` in your home directory to make the server available across all projects:
- ```json
- {
- "mcpServers": {
- "@reapi/mcp-openapi": {
- "command": "npx",
- "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "/path/to/your/specs"],
- "env": {}
- }
- }
- }
- ```
- ### Enable in Cursor Settings
- After adding the configuration:
- 1. Open Cursor IDE
- 2. Go to Settings > Cursor Settings > MCP
- 3. Enable the @reapi/mcp-openapi server
- 4. Click the refresh icon next to the server to apply changes
- > **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.
- The server is now ready to use. When you add new OpenAPI specifications to your directory, you can refresh the catalog by:
- 1. Opening Cursor's chat panel
- 2. Typing one of these prompts:
- ```
- "Please refresh the API catalog"
- "Reload the OpenAPI specifications"
- ```
- ### OpenAPI Specification Requirements
- 1. Place your OpenAPI 3.x specifications in the target directory:
- - Supports both JSON and YAML formats
- - Files should have `.json`, `.yaml`, or `.yml` extensions
- - Scanner will automatically discover and process all specification files
- 2. Specification ID Configuration:
- - By default, the filename (without extension) is used as the specification ID
- - To specify a custom ID, add `x-spec-id` in the OpenAPI info object:
- ```yaml
- openapi: 3.0.0
- info:
- title: My API
- version: 1.0.0
- x-spec-id: my-custom-api-id # Custom specification ID
- ```
- > **Important**: Setting a custom `x-spec-id` is crucial when working with multiple specifications that have:
- > - Similar or identical endpoint paths
- > - Same schema names
- > - Overlapping operation IDs
- >
- > The spec ID helps distinguish between these similar resources and prevents naming conflicts. For example:
- > ```yaml
- > # user-service.yaml
- > info:
- > x-spec-id: user-service
- > paths:
- > /users:
- > get: ...
- >
- > # admin-service.yaml
- > info:
- > x-spec-id: admin-service
- > paths:
- > /users:
- > get: ...
- > ```
- > Now you can reference these endpoints specifically as `user-service/users` and `admin-service/users`
- ## How It Works
- 1. The server scans the specified directory for OpenAPI specification files
- 2. It processes and dereferences the specifications for complete context
- 3. Creates and maintains a catalog of all API operations and schemas
- 4. Exposes this information through the MCP protocol
- 5. IDE integrations can then use this information to:
- - Provide API context to LLMs
- - Enable intelligent code completion
- - Assist in API integration
- - Generate API-aware code snippets
- ## Tools
- 1. `refresh-api-catalog`
- - Refresh the API catalog
- - Returns: Success message when catalog is refreshed
- 2. `get-api-catalog`
- - Get the API catalog, the catalog contains metadata about all openapi specifications, their operations and schemas
- - Returns: Complete API catalog with all specifications, operations, and schemas
- 3. `search-api-operations`
- - Search for operations across specifications
- - Inputs:
- - `query` (string): Search query
- - `specId` (optional string): Specific API specification ID to search within
- - Returns: Matching operations from the API catalog
- 4. `search-api-schemas`
- - Search for schemas across specifications
- - Inputs:
- - `query` (string): Search query
- - `specId` (optional string): Specific API specification ID to search
- - Returns: Matching schemas from the API catalog
- 5. `load-api-operation-by-operationId`
- - Load an operation by operationId
- - Inputs:
- - `specId` (string): API specification ID
- - `operationId` (string): Operation ID to load
- - Returns: Complete operation details
- 6. `load-api-operation-by-path-and-method`
- - Load an operation by path and method
- - Inputs:
- - `specId` (string): API specification ID
- - `path` (string): API endpoint path
- - `method` (string): HTTP method
- - Returns: Complete operation details
- 7. `load-api-schema-by-schemaName`
- - Load a schema by schemaName
- - Inputs:
- - `specId` (string): API specification ID
- - `schemaName` (string): Name of the schema to load
- - Returns: Complete schema details
- ## Roadmap
- 1. **Semantic Search**
- - Enable natural language queries for API operations and schemas
- - Improve search accuracy with semantic understanding
- 2. **Remote Specs Sync**
- - Support syncing OpenAPI specifications from remote sources
- 3. **Code Templates**
- - Expose code templates through MCP protocol
- - Provide reference patterns for LLM code generation
- 4. **Community Contributions**
- - Submit feature requests and bug reports
- - Contribute to improve the server
- ## Example Prompts in Cursor
- Here are some example prompts you can use in Cursor IDE to interact with your APIs:
- 1. **Explore Available APIs**
- ```
- "Show me all available APIs in the catalog with their operations"
- "List all API specifications and their endpoints"
- ```
- 2. **API Operation Details**
- ```
- "Show me the details of the create pet API endpoint"
- "What are the required parameters for creating a new pet?"
- "Explain the response schema for the pet creation endpoint"
- ```
- 3. **Schema and Mock Data**
- ```
- "Generate mock data for the Pet schema"
- "Create a valid request payload for the create pet endpoint"
- "Show me examples of valid pet objects based on the schema"
- ```
- 4. **Code Generation**
- ```
- "Generate an Axios client for the create pet API"
- "Create a TypeScript interface for the Pet schema"
- "Write a React hook that calls the create pet endpoint"
- ```
- 5. **API Integration Assistance**
- ```
- "Help me implement error handling for the pet API endpoints"
- "Generate unit tests for the pet API client"
- "Create a service class that encapsulates all pet-related API calls"
- ```
- 6. **Documentation and Usage**
- ```
- "Show me example usage of the pet API with curl"
- "Generate JSDoc comments for the pet API client methods"
- "Create a README section explaining the pet API integration"
- ```
- 7. **Validation and Types**
- ```
- "Generate Zod validation schema for the Pet model"
- "Create TypeScript types for all pet-related API responses"
- "Help me implement request payload validation for the pet endpoints"
- ```
- 8. **API Search and Discovery**
- ```
- "Find all endpoints related to pet management"
- "Show me all APIs that accept file uploads"
- "List all endpoints that return paginated responses"
- ```
- 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.
- ## Contributing
- Contributions are welcome! Please feel free to submit a Pull Request.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.