OpenAPI MCP Server: Setup Guide, Use Cases & Limitations

What Is OpenAPI MCP Server?

OpenAPI MCP Server loads an OpenAPI specification and exposes the described REST API endpoints as callable tools within Claude, letting you interact with any spec-compliant API directly from your Claude session. It is maintained by janwilmake and published as an active open-source project on GitHub.

Quick Facts

What You Can Do With It

• API exploration: Point the server at any OpenAPI spec and browse available endpoints, parameters, and response schemas without leaving Claude.
• REST testing: Execute live API calls against a running service by having Claude construct and send requests based on the loaded spec.
• Auto-documentation: Use Claude to summarize, explain, or generate human-readable documentation from a raw OpenAPI JSON or YAML file.
• Integration generation: Ask Claude to produce client code, SDK stubs, or integration scaffolding derived from the spec’s operation definitions.

How to Set It Up

Claude Code (CLI)

Run the server on demand using npx — no global install required:

npx mcp-openapi-server
To register it as a persistent MCP server in Claude Code, add the following to your project's `.claude/mcp.json`:

```json
{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["mcp-openapi-server"]
    }
  }
}

Claude Desktop

Add the server block to claude_desktop_config.json (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["mcp-openapi-server"]
    }
  }
}

After saving, restart Claude Desktop to register the server. You will then be able to pass an OpenAPI spec URL or file path to the server as part of your session.

Check the GitHub repository for any additional startup flags (such as how to specify the spec source at launch time), as configuration options may evolve between releases.

Works Best With

OpenAPI MCP Server is documented as compatible with Claude Code and Claude Desktop. Claude Code is the better fit for developer workflows — you can invoke it inline during active coding sessions, pass spec files from local disk, and chain it with other MCP tools. Claude Desktop suits manual API exploration where you want a conversational interface against a spec without a terminal workflow.

Known Limitations

• Authentication handling: Many real-world APIs require API keys, OAuth tokens, or other auth headers. How credentials are injected into requests depends on the server’s implementation — review the repo before pointing it at authenticated endpoints.
• Spec compliance: The server’s behavior depends on how well-formed the OpenAPI spec is. Poorly structured or non-standard specs may cause incomplete tool exposure or parsing errors.
• Rate limits: The server itself imposes no rate limits, but any live API calls it makes are subject to the target API’s own rate limiting and quotas.
• Local vs. remote specs: Confirm whether the server supports both file paths and remote URLs for spec loading before building workflows that depend on either.
• npx latency: Using npx without a cached version introduces a download step on first run, which may cause timeout issues in some MCP client configurations.

Community Resources

• GitHub Repository — primary source for setup instructions, open issues, and release notes
• GitHub Issues — report bugs or search for known problems before opening a new ticket
• TrendScoped MCP Directory — browse related developer-tools MCP servers