OpenAPI Swagger MCP server

openapi-swagger-mcp

A local MCP server that connects your AI assistant to the dev/UAT APIs you configure. Ask it to find an endpoint, explain its inputs, send a request and inspect the response using your Swagger 2.0 or OpenAPI 3.0/3.1 spec.

For example: “Find the order details endpoint and explain the required parameters before calling it.”

You configure the API addresses and authentication in a YAML or JSON file. Your MCP client starts the server, and your assistant uses its ten fixed tools regardless of how many endpoints you have.

New here? Follow Quick start, then try Everyday usage. You do not need to write tool calls yourself.

Already connected? Jump to Choose your next step, Troubleshooting or Tool reference.

Before you start

You need:

• Node.js 22.19 or newer and npm.
• An API you can reach, and its Swagger/OpenAPI spec (a URL or a file).
• An MCP client that can launch a local stdio server.

Use this only against dev/UAT services. The tools send real POST, PUT, PATCH and DELETE requests. There is no rollback and no server-side write gate. A confirmation prompt in your MCP client is the client's feature, not something this server enforces.

Think about where your data goes. Tool arguments and results can be stored in your AI provider's conversation history. Responses are not scrubbed of tokens or personal data. Read secrets from environment variables or files instead of pasting them into the conversation.

Quick start

1. Create a config file

Save this as config.dev.yaml:

services:
  orders:
    baseUrl: http://localhost:8080/api/v1
    spec: http://localhost:8080/v3/api-docs

• orders is the service name the agent uses in tool calls.
• baseUrl is where requests are really sent, including any prefix such as /api/v1.
• spec is the Swagger/OpenAPI URL, or a file path such as ./openapi.json.
• With no auth block, requests are anonymous.

The URLs above are examples. They only work if your own API is running there, so replace them with your dev/UAT addresses.

Before continuing: replace both URLs and save the file. Note its absolute path; you will use that same path in the next two steps.

2. Check the config

npx -y @nhan7777/openapi-swagger-mcp@0.1.2 --config /absolute/path/config.dev.yaml --check

ok: true means the static checks passed. It does not mean the remote spec was fetched or any endpoint was verified: --check makes no network calls, does not log in, and does not create the artifact directory. See Troubleshooting for the report format and exit codes.

Expected result: the command exits with code 0 and the report contains "ok": true. If it does not, fix the reported field before connecting your client.

3. Add the server to your MCP client

For clients that use an mcpServers configuration, add this to the client's MCP config file (not to the YAML file above):

{
  "mcpServers": {
    "api-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@nhan7777/openapi-swagger-mcp@0.1.2",
        "--config",
        "/absolute/path/config.dev.yaml"
      ]
    }
  }
}

The file name and location depend on your client. If your client has a form for command, arguments and environment variables, enter the same values there. Not every client uses the mcpServers format, so adapt the snippet if yours differs. Use absolute paths so the server does not depend on the directory the client starts in.

This server uses stdio: the client starts the process and talks to it over stdin/stdout. There is no web UI and no HTTP port. stdout is reserved for MCP traffic and logs go to stderr. Do not add --check to the client entry, because that mode exits after checking.

4. Connect and check API availability

Shortened. The full README is on GitHub.