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)

---

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]

Key	Default	Description
host	"0.0.0.0"	Address the MCP server listens on. 0.0.0.0 binds all interfaces.
port	8080	Port the MCP server listens on.

[logging]

Key	Default	Description
level	"info"	Log verbosity. One of: debug, info, warning, error.

---

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

Tool	Description
health_check	Returns {"status": "ok"} to confirm the server is running.
list_paths	List all path keys defined in an OpenAPI specification, each with an optional description when present in the Path Item.
get_path_item	Return the full Path Item object for a specific path.
get_operation	Return the Operation object for a specific HTTP method and path.
get_spec_version	Return the specification format version string (e.g. swagger 2.0, openapi 3.0.3).
list_refs_in_path	List all $ref values and their JSON Pointer locations within a path item.
get_component_schema	Return a named schema object from components.schemas.
list_refs_in_schema	List all $ref values within a schema, resolved by name or $ref string.
resolve_ref	Resolve an internal $ref string and return the target object with its canonical pointer.

---

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.