OpenAPI MCP Server

Talk to any OpenAPI (v3.1) compliant API through Claude Desktop!

This tool creates a Model Context Protocol (MCP) server that acts as a proxy for any API that has an OpenAPI v3.1 specification. This allows you to use Claude Desktop to easily interact with both local and remote server APIs.

If you're having trouble with Claude crashing or specs not working put them through our spec cleaner app this tidies up some open api schemas to help them be LLM-readable.

What does it do?

This proxy automatically converts OpenAPI endpoints into Claude tools, allowing Claude to:

1. Discover available API endpoints and understand their purpose
2. Know what parameters are required and their types
3. Make API calls on your behalf
4. Handle the responses appropriately

For example, if you have a Petstore API with this endpoint:

/pets/{petId}:
  get:
    operationId: getPetById
    summary: Returns a pet by ID
    parameters:
      - name: petId
        in: path
        description: ID of pet to return
        required: true
        schema:
          type: integer

Claude will see this as a tool it can use:

You can then ask Claude natural questions like:

• "Can you fetch the details for pet ID 123?"
• "What's the status of my pet with ID 456?"

Claude will understand the context and make the appropriate API calls.

File Upload Support

The proxy supports file uploads for APIs that accept multipart/form-data. When an endpoint accepts file uploads (indicated by type: string, format: binary in the OpenAPI spec), you can provide local file paths and the proxy will handle reading and uploading the files.

Example Use Cases

1. Profile Picture Upload

/users/{userId}/avatar:
  post:
    summary: Upload a user's profile picture
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              avatar:
                type: string
                format: binary
                description: Profile picture (JPEG/PNG)
              cropInfo:
                type: object
                properties:
                  x: { type: number }
                  y: { type: number }
                  width: { type: number }
                  height: { type: number }

You can ask Claude:

• "Upload my new profile picture from ~/Pictures/profile.jpg"
• "Update my avatar with ~/Downloads/photo.png and crop it to 200x200"

2. Document Processing

/documents:
  post:
    summary: Upload documents for processing
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              document:
                type: string
                format: binary
                description: PDF or Word document
              language:
                type: string
                enum: [en, es, fr]
                description: Document language
              processOCR:
                type: boolean
                description: Whether to extract text using OCR

Natural language commands:

• "Process the document at ~/Documents/contract.pdf in English with OCR enabled"
• "Upload ~/Downloads/report.docx and set the language to French"

3. Batch File Upload

/batch-upload:
  post:
    summary: Upload multiple files in one request
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              files:
                type: array
                items:
                  type: string
                  format: binary
              tags:
                type: array
                items:
                  type: string

You can say:

• "Upload these three files: ~/data1.csv, ~/data2.csv, and ~/data3.csv with tags 'monthly-report'"
• "Process the files in ~/exports/ with tags 'raw-data', 'june-2023'"

Important Considerations

1. Security

   • File paths are resolved relative to the current working directory
   • Access is restricted to files the user has permission to read
   • Sensitive files (like ~/.ssh/id_rsa) require explicit user confirmation
   • File contents are only read when making the actual API request

2. Performance

   • Large files are streamed directly from disk to the API
   • Memory usage is optimized for large files
   • Progress reporting is available for large uploads

3. Limitations

   • Maximum file size is determined by the target API
   • Only local files are supported (no remote URLs)
   • Some file types may be restricted by the API

Getting Started

1. Configure Claude Desktop: Add this to your claude_desktop_config.json:

   {
     "mcpServers": {
       "petstore-api": {
         "command": "npx",
         "args": ["openapi-mcp-server", "/abs/path/to/petstore-openapi.json"]
       }
     }
   }
   

2. Restart Claude Desktop and start interacting with your API!

Examples

This repository includes a complete example of a Petstore API server that you can use to test the OpenAPI MCP Server. The example server implements a basic CRUD API for managing pets, making it perfect for learning how to use this tool.

See examples/README.md for instructions on running the example server.

Use Cases

1. Local Development

   • Test your APIs through natural conversation
   • Debug endpoints without writing code
   • Explore API capabilities interactively

2. API Integration

   • Quickly test third-party APIs
   • Prototype integrations before writing code
   • Learn new APIs through conversation

3. Documentation

   • Ask questions about API endpoints
   • Get examples of how to use endpoints
   • Understand error conditions

Limitations

• Currently supports OpenAPI v3.1 specs only
• Response handling is optimized for JSON/text responses
• File uploads support local files only (no remote URLs)
• Streaming responses not yet implemented

Development

Outstanding tasks are listed in TODO.md.

Basics:

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build

# Link the project to your global node_modules so that npx works
npm link

# Now start claude desktop to use

# After making changes run build again before restarting claude desktop
pnpm build

# Now restart claude desktop to run with latest changes

License

MIT

---

Built with ❤️ for making APIs more accessible through natural language.