Provides tools to query and process Swagger/OpenAPI JSON documents, enabling efficient management of API documentation with features like multi-project handling, smart $ref resolution, and advanced search.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@swagger-json-mcp list available swagger projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A powerful Model Context Protocol (MCP) server designed to efficiently query and process large Swagger/OpenAPI JSON documents. This server solves the common problem of LLMs being unable to process large API documentation files (typically 4000+ lines) by providing structured, intelligent query interfaces.
📋 Multi-project Management: Seamlessly handle multiple Swagger/OpenAPI projects
🔍 Smart $ref Resolution: Automatically resolve JSON Schema references and handle circular dependencies
🔎 Intelligent Search: Advanced search capabilities for APIs and schemas with fuzzy matching
⚡ Efficient Querying: Get specific API or schema information without loading entire documents
🔄 Real-time Updates: Automatically detect and reload changes in Swagger files
list_swaggers: List all available Swagger projects
get_swagger_overview: Get project overview and statistics
get_api_info: Retrieve complete API information with resolved schemas
get_schema: Get fully resolved schema definitions
search_apis: Search API endpoints with advanced filtering
search_schemas: Search schema definitions with type filtering
Related MCP server: mcp-swagger-schema
swagger-json-mcp/
├── src/
│ ├── core/ # Core functionality modules
│ │ ├── SwaggerParser.ts # Swagger JSON parser
│ │ ├── SchemaResolver.ts # $ref reference resolver
│ │ └── SwaggerManager.ts # Multi-project manager
│ ├── mcp/ # MCP server implementation
│ │ ├── tools/ # MCP tool definitions
│ │ └── types.ts # TypeScript type definitions
│ ├── utils/ # Utility functions
│ └── index.ts # Main entry point
├── docs/ # Swagger documentation directory
│ └── [project-name]/ # Individual project folders
│ └── swagger.json # Swagger/OpenAPI JSON files
├── package.json
├── tsconfig.json
└── README.mdNode.js >= 18.0.0
pnpm >= 8.0.0
# Clone the repository
git clone <repository-url>
cd swagger-json-mcp
# Install dependencies
pnpm install
# Build the project
pnpm build
# Run tests
pnpm testCreate project directories under docs/ and place your swagger.json files:
docs/
├── your-api-project/
│ └── swagger.json
└── another-project/
└── swagger.json# Development mode
pnpm dev
# Production mode
pnpm startAdd to your MCP client configuration:
{
"mcpServers": {
"swagger-json": {
"command": "node",
"args": ["path/to/swagger-json-mcp/dist/index.js"],
"env": {}
}
}
}// MCP Tool Call
{
"name": "list_swaggers",
"arguments": {}
}
// Response
{
"projects": [
{
"name": "your-api-project",
"title": "Your API",
"version": "1.0.0",
"apiCount": 42,
"schemaCount": 28
}
]
}// MCP Tool Call
{
"name": "get_api_info",
"arguments": {
"swaggerName": "your-api-project",
"path": "/api/users",
"method": "post"
}
}
// Response includes fully resolved schemas
{
"path": "/api/users",
"method": "post",
"summary": "Create user",
"requestBody": {
// Fully resolved schema without $ref
},
"responses": {
// Fully resolved response schemas
}
}// MCP Tool Call
{
"name": "search_apis",
"arguments": {
"query": "user login",
"swaggerName": "your-api-project",
"method": "post"
}
}
// Response
{
"results": [
{
"path": "/auth/login",
"method": "post",
"summary": "User login",
"score": 0.95
}
]
}// MCP Tool Call
{
"name": "get_schema",
"arguments": {
"swaggerName": "your-api-project",
"schemaName": "UserProfile",
"maxDepth": 10
}
}
// Response includes all nested schemas resolved
{
"schema": {
"type": "object",
"properties": {
// All $ref references resolved recursively
}
},
"dependencies": ["Address", "ContactInfo"],
"circularReferences": []
}pnpm build # Compile TypeScript
pnpm dev # Development with hot reload
pnpm test # Run test suite
pnpm lint # Run ESLint
pnpm typecheck # TypeScript type checking
pnpm prettier # Format code
pnpm clean # Clean build directoryTypeScript: Strict mode enabled with comprehensive type definitions
ESLint: Configured with TypeScript and Prettier rules
Vitest: Fast unit testing with full coverage
Prettier: Consistent code formatting
# Run all tests
pnpm test
# Run tests in watch mode
pnpm test --watch
# Run tests with coverage
pnpm test --coverageValidates and parses Swagger/OpenAPI JSON files
Handles multiple OpenAPI versions (2.0, 3.0.x)
Provides structured access to API definitions
Recursively resolves $ref references
Detects and handles circular dependencies
Configurable resolution depth
Caches resolved schemas for performance
Manages multiple Swagger projects
Automatic file discovery and loading
Project lifecycle management
Thread-safe operations
Full compliance with Model Context Protocol specification
Structured tool definitions with comprehensive validation
Error handling and logging
Async/await throughout for optimal performance
# Optional: Set log level
LOG_LEVEL=info
# Optional: Custom docs directory
DOCS_DIR=./custom-docs
# Optional: Maximum schema resolution depth
MAX_SCHEMA_DEPTH=10Modify src/utils/logger.ts for custom logging
Extend src/core/SwaggerManager.ts for additional project types
Add new MCP tools in src/mcp/tools/
Fork the repository
Create a feature branch: git checkout -b feature/new-feature
Make your changes with tests
Run the test suite: pnpm test
Ensure code quality: pnpm lint && pnpm typecheck
Commit changes: git commit -m 'Add new feature'
Push to branch: git push origin feature/new-feature
Submit a pull request
Follow existing code style and conventions
Add tests for new functionality
Update documentation for API changes
Ensure TypeScript compliance
Write clear, descriptive commit messages
This project is licensed under the MIT License - see the LICENSE file for details.
Project not loading
Verify docs/ directory structure
Check swagger.json file validity
Ensure proper JSON formatting
$ref resolution failing
Validate JSON Schema reference paths
Check for circular references
Verify component definitions exist
MCP connection issues
Confirm server startup success
Validate MCP client configuration
Check Node.js version compatibility
Enable detailed logging:
LOG_LEVEL=debug pnpm startModel Context Protocol - Protocol specification
OpenAPI Specification - API documentation standard
TypeScript - Type-safe JavaScript
Vitest - Fast testing framework
Made with ❤️ for better API documentation accessibility
獲取特定 API 的完整資訊，自動解析所有相關 schemas
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | API 路徑（例如：/login） | |
| method | Yes | HTTP 方法（例如：get, post, put, delete） | |
| swaggerName | Yes | Swagger 檔案名稱 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It does add one useful behavioral detail—that all related schemas are automatically parsed—which goes beyond a simple 'get' statement. However, it does not disclose what 'complete info' includes, whether authentication is needed, or any potential performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, with no wasted words. It effectively communicates the core function and the schema-parsing behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple read-only tool but omits details about the return format, how to discover valid swaggerName values, or any constraints. Given there is no output schema and no annotations, a more complete description would be beneficial, but it still manages to be minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all three parameters (swaggerName, path, method), achieving 100% coverage. The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate; the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: '獲取特定 API 的完整資訊' (get complete info for a specific API) and adds '自動解析所有相關 schemas' (automatically parse all related schemas), which distinguishes it from sibling tools like get_schema or search_apis. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is provided. The description does not mention alternatives, prerequisites, or contexts where this tool should be preferred over siblings. The user is left to infer that it is for specific API lookups, but no explicit usage direction is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
獲取指定 schema 的完整定義，自動解析所有 $ref 引用
| Name | Required | Description | Default |
|---|---|---|---|
| maxDepth | No | 最大解析深度，預設為 10 | |
| schemaName | Yes | Schema 名稱 | |
| swaggerName | Yes | Swagger 檔案名稱 | |
| includeCircular | No | 是否包含循環引用，預設為 true |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions automatic $ref resolution, but omits critical behaviors such as how maxDepth limits resolution depth, how includeCircular handles circular references, and what the return format looks like. This is a significant gap given the tool's complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose and adds the key feature of $ref resolution. No unnecessary words, and it is appropriately sized for the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a fully documented schema, the tool lacks an output schema and annotations, and the description is too brief to explain how parameters like maxDepth and includeCircular affect the result or what the response structure is. Sibling tools are not addressed, and the behavior around circular references and depth is left unclear, making the description incomplete for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already explains all four parameters with descriptions. The description adds no additional parameter semantics, but the baseline of 3 is appropriate since the schema fully documents the parameters and their defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the complete schema definition and automatically resolves all $ref references, which differentiates it from sibling tools like search_schemas or get_swagger_overview. The verb '獲取' and resource 'schema' are explicit, and the $ref resolution detail adds specificity beyond the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a full schema definition with resolved references is needed, but it provides no explicit guidance on when to use this tool versus alternatives like search_schemas or get_swagger_overview. There are no exclusions or alternative recommendations, leaving the usage context to be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
獲取 Swagger 檔案的整體概覽和統計資訊
| Name | Required | Description | Default |
|---|---|---|---|
| swaggerName | Yes | Swagger 檔案名稱 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It only says 'overview and statistics' but does not specify what data is returned, whether it is read-only, if there are pagination or size limits, or what the output structure looks like. This lack of detail is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the verb '獲取' and clearly identifies the resource. There is no unnecessary wording or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 parameter, no output schema), but the description could be more complete by elaborating on what 'overview and statistics' includes. Without an output schema, the agent must infer return values, and the vague phrasing leaves room for ambiguity. It is minimally adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the only parameter (swaggerName) with 100% coverage, so the baseline is 3. The description does not add any additional meaning to the parameter beyond what the schema provides, which is acceptable for a single, self-explanatory parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('獲取' - get) and resource ('Swagger 檔案的整體概覽和統計資訊' - overall overview and statistics of the Swagger file), which is specific enough to differentiate from sibling tools like get_schema or get_api_info. However, it doesn't explicitly contrast with those siblings, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_swaggers, get_schema, or search_apis. There is no mention of prerequisites (e.g., needing a Swagger file name from list_swaggers) or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出所有可用的 Swagger 檔案
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only states the basic action, but does not disclose output format, potential size of the list, or any side effects. 'List' implies read-only, but no further context is offered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It conveys exactly what the tool does in an appropriately concise manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters and no output schema, so the description is minimally viable. However, it does not clarify how the returned list is structured or how it relates to siblings like get_swagger_overview, leaving some ambiguity for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so the baseline of 4 applies. The description correctly implies no parameters are needed, and the empty input schema confirms this. No additional parameter semantics are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('list') and the resource ('all available Swagger files'), distinguishing it from siblings like get_swagger_overview and search_apis which are more specific or filter-based.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like search_apis. The description implies usage for listing all swaggers, but does not clarify scenarios where siblings would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
搜索 API endpoints，支援模糊搜索和多種過濾條件
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | 限制搜索的標籤（可選） | |
| limit | No | 最大回傳結果數量，預設為 10，最大 100 | |
| query | Yes | 搜索關鍵字（可搜索路徑、摘要、描述、operationId、標籤） | |
| method | No | HTTP 方法過濾（如：get, post, put, delete）（可選） | |
| swaggerName | No | 限制搜索的 Swagger 檔案名稱（可選） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses some behavioral traits: fuzzy search and multiple filter conditions. However, it does not mention whether the operation is read-only, what the return structure looks like, or whether there are pagination or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that immediately states the action and resource. There is no fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 5 parameters fully described in the schema, the description is adequate but incomplete. It lacks details about the return format (though no output schema exists), and it does not mention how search results are ordered or what fields are included.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds little beyond the schema: 'fuzzy search' hints at query matching semantics, but the filter parameters (tag, method, swaggerName) are already well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '搜索 API endpoints' (search API endpoints). It distinguishes from sibling search_schemas by targeting endpoints rather than schemas, and adds specific capabilities (fuzzy search, multiple filter conditions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like search_schemas or get_api_info. There are no exclusions, prerequisites, or indications of preferred use cases beyond the basic search purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
搜索 schema 定義，支援模糊搜索和類型過濾
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Schema 類型過濾（如：object, string, array, number）（可選） | |
| limit | No | 最大回傳結果數量，預設為 10，最大 100 | |
| query | Yes | 搜索關鍵字（可搜索 schema 名稱、描述、屬性名稱） | |
| swaggerName | No | 限制搜索的 Swagger 檔案名稱（可選） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions fuzzy search and type filtering, but does not explicitly disclose the read-only nature, response format, or any side effects. For a search tool this is partially adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word adds value, clearly stating the action and key features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description does not explain what results look like or provide sufficient context for selecting this tool over siblings. The tool has four parameters, and the description is too minimal to be fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds the 'fuzzy search' behavior, which is not explicitly stated in the query parameter description, providing additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'search schema definitions' (搜索 schema 定義) with specific features (fuzzy search and type filtering), distinguishing it from sibling tools like search_apis and get_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb 'search' but there is no explicit guidance on when to use this tool versus siblings like get_schema or search_apis. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0get_api_infoget_schemaget_swagger_overviewlist_swaggerssearch_apissearch_schemasEach tool targets a distinct resource and action: listing swaggers, getting overviews, retrieving schemas, retrieving API info, and searching APIs or schemas. No overlap in purpose; agents can easily select the right tool.
All tool names follow a consistent verb_noun pattern using snake_case (list_*, get_*, search_*). The nouns are clear and descriptive, with only minor pluralization inconsistencies that do not affect predictability.
Six tools is well-scoped for a Swagger/OpenAPI inspection server. Each tool covers a distinct aspect of reading and exploring API definitions without being excessive or minimal.
The tool surface provides a complete read-only workflow: list available Swagger files, get overview statistics, retrieve detailed schema definitions with $ref resolution, get full API info, and search for APIs/schemas. No obvious gaps for a browsing/inspection use case.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for AI access to Swagger by SmartBear.
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/LLM-MCP-Servers/swagger-json-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
