MCP 服务器

mcp-openapi-query

A FastMCP server that enables AI applications to navigate and query OpenAPI specifications, including resolving $ref pointers and inspecting paths and operations.

README

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

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

Copy the example config and edit it:
```
cp config.toml.example config.toml
```
Start the server:
```
docker compose up -d
```

Option B — Run from Source

Install uv if you haven't already.
Install dependencies:
```
uv sync
```
Copy the example config and edit it:
```
cp config.toml.example config.toml
```
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

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.