mcp-openapi-query

A FastMCP server for navigating and querying OpenAPI specifications. Connect any MCP-compatible AI application to this server so it can explore API schemas, resolve $ref pointers, and inspect paths and operations without reading an entire spec file at once.

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools and services. This server implements MCP over HTTP so any MCP-compatible AI application can reach it.

Prerequisites

• Docker — for the Docker Compose deployment path

• uv — for the source deployment path (see Installing uv)

Related MCP server: mcp-swagger-schema

Quick Start

Option A — Docker Compose

1. Create a docker-compose.yml:

   services:
     mcp-openapi-query:
       image: sesopenko/mcp-openapi-query:latest
       ports:
         - "8080:8080"
       volumes:
         - ./config.toml:/config/config.toml:ro
       restart: unless-stopped

2. Copy the example config and edit it:

   cp config.toml.example config.toml

3. Start the server:

   docker compose up -d

Option B — Run from Source

1. Install uv if you haven't already.

2. Install dependencies:

   uv sync

3. Copy the example config and edit it:

   cp config.toml.example config.toml

4. Start the server:

   uv run python -m mcp_openapi_query

Security

This server has no authentication on its MCP endpoint. It is designed for LAN use only.

Do not expose this server directly to the internet.

If you need to access it remotely, place it behind a reverse proxy that handles TLS termination and access control. Configuring a reverse proxy is outside the scope of this project.

Configuration

Create a config.toml in the working directory (or pass --config <path>):

[server]
host = "0.0.0.0"
port = 8080

[logging]
level = "info"

[server]

[logging]

Connecting an AI Application

This server uses the Streamable HTTP MCP transport. Clients communicate via HTTP POST with streaming responses — opening the endpoint in a browser will return a Not Acceptable error, which is expected.

Point your MCP-compatible AI application at the server's MCP endpoint:

http://<host>:<port>/mcp

For example, if the server is running on 192.168.1.10 with the default port:

http://192.168.1.10:8080/mcp

Consult your AI application's documentation for how to register an MCP server. Ensure it supports the Streamable HTTP transport (most modern MCP clients do).

Using with Claude Code

1. Start the server

Create a docker-compose.yml and a minimal config.toml, then start the server:

services:
  mcp-openapi-query:
    image: sesopenko/mcp-openapi-query:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.toml:/config/config.toml:ro
    restart: unless-stopped

[server]
host = "0.0.0.0"
port = 8080

[logging]
level = "info"

docker compose up -d

2. Register the MCP server in Claude Code

Add the server to your project's MCP configuration. Run this from your project root:

claude mcp add --transport http openapi-query http://localhost:8080/mcp

Or add it manually to .claude/settings.json in your project:

{
  "mcpServers": {
    "openapi-query": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

3. Verify the connection

In a Claude Code session, run:

/mcp

The openapi-query server should appear as connected. You can also call health_check directly to confirm the server is reachable.

Available Tools

Running Tests

uv run pytest tests/unit/

Contributing / Maintaining

See MAINTAINERS.md for setup, development commands, AI agent rails, and how to run tests.

License

Copyright (c) Sean Esopenko 2026

This project is licensed under the GNU General Public License v3.0.

Acknowledgement: Riding on the Backs of Giants

This project was built with the assistance of Claude Code, an AI coding assistant developed by Anthropic.

AI assistants like Claude are trained on enormous amounts of data — much of it written by the open-source community: the libraries, tools, documentation, and decades of shared knowledge that developers have contributed freely. Without that foundation, tools like this would not be possible.

In recognition of that debt, this project is released under the GNU General Public License v3.0. The GPL ensures that this code — and any derivative work — remains open source. It is a small act of reciprocity: giving back to the commons that made it possible.

To every developer who ever pushed a commit to a public repo, wrote a Stack Overflow answer, or published a package under an open license — thank you.