api-docs-mcp

MCP server for API documentation, supporting GraphQL, OpenAPI/Swagger, and gRPC from local files or remote URLs

3 stars TypeScriptOthers Updated Aug 17, 2026

aianthropicgraphqlllmmcpopenapi

Documentation

API Docs MCP

Model Context Protocol (MCP) server that provides tools for interacting with API documentation. Supports GraphQL, OpenAPI/Swagger, and gRPC specifications, fetching schema definitions from various sources (local files or remote URLs), caching them, and exposing them through a set of tools.

MCP Platforms

Features

Dynamic Tool Registration: Automatically discovers and registers tools from a specified directory.
API Documentation Retrieval: Provides tools to list available API methods (`api_docs`) and retrieve detailed documentation for specific methods (`api_search`).
Schema Caching: Caches API schema information to reduce redundant fetches and improve performance.
Multiple Source Support:
- GraphQL: Supports loading GraphQL schemas from `graphql` / `gql` files or `json` introspection results (local files or remote URLs).
- OpenAPI/Swagger: Supports loading OpenAPI/Swagger `yaml` / `yml` / `json` schemas from local files or remote URLs.
- gRPC: Supports loading gRPC schemas from `proto` files or via gRPC reflection from remote URLs.
Environment-based Configuration: Configures API sources via the `API_SOURCES` environment variable, allowing flexible deployment and management.
Automatic Cache Refresh: Periodically refreshes cached schema data to ensure up-to-date documentation.

Example Use Cases

OpenAPI Petstore retrieval docs

GraphQL retrieval docs

Multiple Sources retrieval docs

Architecture

The `api-docs-mcp` project is designed as an MCP server that integrates with various API documentation sources.

mermaid

graph TD
    mcpServer[MCP Server] e1@--> tools(Tools:api_docs / api_search);
    tools e2@--> cacheManager{Cache Manager};
    cacheManager e3@--> configuration[Configuration:API_SOURCES env var];
    configuration e4@--> schemaSources{Schema Sources};
    schemaSources e5@-- FileSource--> localFiles(Local Files:.graphql, .json, .yaml, .proto);
    schemaSources e6@-- UrlSource--> remoteUrls(Remote URLs:GraphQL Endpoints, OpenAPI/Swagger Endpoints, gRPC Endpoints);
    localFiles e7@--> processor[Schema Processors];
    remoteUrls e8@--> processor;
    processor e9@--> cacheManager;
    processor e10@--> openAPIProcessor(OpenAPI Processor:OpenAPI/Swagger);
    processor e11@--> graphQLProcessor(GraphQL Processor);
    processor e12@--> grpcProcessor(gRPC Processor)
    cacheManager e13@--Cached Data--> tools;

    subgraph Core Components
        mcpServer
        tools
        cacheManager
        configuration
    end

    subgraph Data Flow
        schemaSources
        localFiles
        remoteUrls
        processor
        openAPIProcessor
        graphQLProcessor
        grpcProcessor
    end

    e1@{ animate: true }
    e2@{ animate: true }
    e3@{ animate: true }
    e4@{ animate: true }
    e5@{ animate: true }
    e6@{ animate: true }
    e7@{ animate: true }
    e8@{ animate: true }
    e9@{ animate: true }
    e10@{ animate: true }
    e11@{ animate: true }
    e12@{ animate: true }
    e13@{ animate: true }

Flow of Operations:

1. Server Initialization: The `index.ts` entry point initializes the MCP server and dynamically registers tools defined in the `src/tools` directory.

2. Configuration Loading: The `CacheManager` loads API source configurations from the `API_SOURCES` environment variable via `src/utils/config.ts`.

3. Schema Fetching & Caching:

4. Tool Usage:

Installation

To set up the `api-docs-mcp` server, follow these steps:

1. Clone the repository:

bash

git clone https://github.com/EliFuzz/api-docs-mcp.git
   cd api-docs-mcp

2. Install dependencies:

bash

pnpm install

3. Build the project:

bash

pnpm build

Configuration

The server's behavior is controlled by the `API_SOURCES` environment variable. This variable should contain a JSON string representing an array of `SchemaSource` objects. Each `SchemaSource` can be either a `FileSource` or a `UrlSource`.

`FileSource` Example

For a local GraphQL schema:

json

{
  "name": "MyGraphQLFile",
  "path": "/path/to/your/schema.graphql",
  "type": "gql"
}

For a local OpenAPI JSON schema:

json

{
  "name": "MyOpenAPIFile",
  "path": "/path/to/your/openapi.json",
  "type": "api"
}

For a local gRPC proto file:

json

{
  "name": "MyGrpcFile",
  "path": "/path/to/your/service.proto",
  "type": "grpc"
}

`UrlSource` Example

For a remote GraphQL endpoint:

json

{
  "name": "GitHubGraphQL",
  "method": "POST",
  "url": "https://api.github.com/graphql",
  "headers": {
    "Authorization": "Bearer YOUR_GITHUB_TOKEN"
  },
  "type": "gql"
}

For a remote OpenAPI endpoint:

json

{
  "name": "PetstoreAPI",
  "method": "GET",
  "url": "https://petstore.swagger.io/v2/swagger.json",
  "type": "api"
}

For a remote gRPC endpoint with reflection:

json

{
  "name": "MyGrpcService",
  "url": "grpc://localhost:9090",
  "type": "grpc"
}

Setting the `API_SOURCES` Environment Variable

You can set this in your shell before running the server:

bash

export API_SOURCES='[{"name": "MyGraphQLFile", "path": "./example/fixtures/graphql/graphql-schema.graphql", "type": "gql"}, {"name": "PetstoreAPI", "method": "GET", "url": "https://petstore.swagger.io/v2/swagger.json", "type": "api"}]'

Or in `mcp.json` for MCP execution:

json

"api-docs-mcp": {
    "type": "stdio",
    "command": "npx",
    "args": [ "api-docs-mcp" ],
    "env": {
        "API_SOURCES": "[{\"name\": \"MyGraphQLFile\", \"path\": \"./example/fixtures/graphql/graphql-schema.graphql\", \"type\": \"gql\"}, {\"name\": \"PetstoreAPI\", \"method\": \"GET\", \"url\": \"https://petstore.swagger.io/v2/swagger.json\", \"type\": \"api\"}]"
    }
}

Usage

Once configured and running, the `api-docs-mcp` server exposes two primary tools: `api_docs` and `api_search`.

API Docs Tool

This tool provides a list of all available API methods from the configured sources.

Name: `api_docs`

Description: Get a list of all available API methods.

Input Schema:

typescript

{
    sourceName?: string; // The name of the API source (e.g., "GitHub") from MCP configuration environment variables. If not provided, docs from all sources will be returned.
}

Output Schema:

typescript

{
  sources: Array;
  }>;
}

Output Example:

json

{
  "sources": [
    {
      "sourceName": "GitHubGraphQL",
      "resources": [
        {
          "resourceName": "getUser",
          "resourceType": "query",
          "resourceDescription": "Fetch a user by username"
        },
        {
          "resourceName": "createIssue",
          "resourceType": "mutation",
          "resourceDescription": "Create a new issue in a repository"
        }
      ]
    },
    {
      "sourceName": "PetstoreAPI",
      "resources": [
        {
          "resourceName": "getPetById",
          "resourceType": "GET",
          "resourceDescription": "Find pet by ID"
        },
        {
          "resourceName": "addPet",
          "resourceType": "POST",
          "resourceDescription": "Add a new pet to the store"
        }
      ]
    }
  ]
}

API Search Tool

This tool provides detailed documentation for a specific API method.

Name: `api_search`

Description: Search for a specific API method by name and get its full definition.

Input Schema:

typescript

{
  resourceName: string; // The exact resource name of the API method to search for that was provided in `api_docs` tool's output
}

Output Schema:

typescript

{
  details: Array;
  }>;
}

Output Example:

json

{
  "details": [
    {
      "sourceName": "GitHubGraphQL",
      "resources": [
        {
          "resourceName": "getUser",
          "resourceType": "query",
          "resourceDescription": "Fetch a user by username",
          "details": {
            "request": "{ username: String! }",
            "response": "{ id: ID!, login: String!, name: String }",
            "error": "{ message: String!, code: Int! }"
          }
        }
      ]
    }
  ]
}

Development

Running the Server Locally

1. Set the `API_SOURCES` environment variable as described in the Configuration section.

2. Start the server:

bash

pnpm start

The server will connect to a `StdioServerTransport`, meaning it will communicate over standard input/output.

Project Structure

markdown

.
├── src/
│ ├── api/ # OpenAPI/Swagger schema processing
│ │ └── api.ts
│ ├── gql/ # GraphQL schema processing
│ │ └── gql.ts
│ ├── grpc/ # gRPC schema processing
│ │ └── grpc.ts
│ ├── tools/ # MCP tools definitions
│ │ ├── api_docs.ts
│ │ └── api_search.ts
│ ├── utils/ # Utility functions (cache, config, fetch, file, source)
│ │ ├── cache.ts
│ │ ├── config.ts
│ │ ├── fetch.ts
│ │ ├── file.ts
│ │ └── source.ts
│ ├── index.ts # Main entry point
│ └── server.ts # MCP server setup and tool registration
└── package.json # Project dependencies and scripts
└── README.md # This file

Contributing

Contributions are welcome! Please feel free to open issues or submit pull requests.

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Frequently asked questions

What is api-docs-mcp?

api-docs-mcp is MCP server for API documentation, supporting GraphQL, OpenAPI/Swagger, and gRPC from local files or remote URLs

How do I install api-docs-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is api-docs-mcp open source?

Yes — it is hosted on GitHub at https://github.com/EliFuzz/api-docs-mcp and has 3 stars.

Related MCP tools

tuui

A desktop MCP client designed as a tool unitary utility integration, accelerating AI adoption through the Model Context Protocol (MCP) and enabling cross-vendor LLM API orchestration.

1,153 TypeScript

agentagentic-aiai+17

repomix

📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Lan...

19,761 TypeScript

aianthropicartificial-intelligence+17

superglue

superglue (YC W25) builds integrations and tools from natural language. Get production-grade tools for long tail and enterprise systems.

2,056 TypeScript

apiapi-gatewayetl-automation+15

mcp

Official Microsoft Learn MCP Server and CLI tool – powering LLMs and AI agents with real-time, trusted Microsoft docs & code samples.

1,872 TypeScript

aiai-agentsdocumentation+9

codesight

Universal AI context generator. Saves thousands of tokens per conversation in Claude Code, Cursor, Copilot, Codex, and more.

1,397 TypeScript

aiclaudecli+11

octocode

Code research platform for AI agents; find, understand, and prove context across your code and all of GitHub, in a fraction of the tokens. One toolset, MCP or CLI

923 TypeScript

aiclaude-aicursor-ai+17

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP

Documentation

API Docs MCP

Table of Contents

MCP Platforms

Features

Example Use Cases

OpenAPI Petstore retrieval docs

GraphQL retrieval docs

Multiple Sources retrieval docs

Architecture

Installation

Configuration

`FileSource` Example

`UrlSource` Example

Setting the `API_SOURCES` Environment Variable

Usage

API Docs Tool

API Search Tool

Development

Running the Server Locally

Project Structure

Contributing

License

Frequently asked questions

What is api-docs-mcp?

How do I install api-docs-mcp?

Is api-docs-mcp open source?

Related MCP tools