-
security-
license-
qualityAn MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.
Last updated -
8
MIT License
Handles environment variables through .env files for storing and managing API credentials securely
Enables interaction with GitHub's API, allowing for operations like retrieving user repositories through tools like 'github_getUser'
Provides access to OpenAI's API services through automatic tool generation from OpenAPI specifications
Integrates with Swagger/OpenAPI specifications to automatically convert API definitions into usable MCP tools
Supports parsing of YAML-formatted OpenAPI specifications for tool generation
Built with FastMCP for TypeScript.
āØ Features
šÆ Zero Configuration: Filesystem is the interface - just drop OpenAPI specs in a folder
š Auto Authentication: Simple
.envfile with{API_NAME}_API_KEYpatternš·ļø Namespace Isolation: Multiple APIs coexist cleanly (e.g.,
petstore_getPet,github_getUser)š Full OpenAPI Support: Handles parameters, request bodies, authentication, and responses
š Multiple Transports: Support for stdio and HTTP streaming
š Built-in Debugging: List command to see loaded specs and tools
š Quick Start
1ļøā£ Install (optional)
npm install -g specbridge
2ļøā£ Create a specs folder
mkdir ~/mcp-apis
3ļøā£ Add OpenAPI specs
Drop any .json, .yaml, or .yml OpenAPI specification files into your specs folder:
# Example: Download the Petstore spec
curl -o ~/mcp-apis/petstore.json https://petstore3.swagger.io/api/v3/openapi.json
4ļøā£ Configure authentication (optional)
Create a .env file in your specs folder:
# ~/mcp-apis/.env
PETSTORE_API_KEY=your_api_key_here
GITHUB_TOKEN=ghp_your_github_token
OPENAI_API_KEY=sk-your_openai_key
5ļøā£ Add to MCP client configuration
For Claude Desktop or Cursor, add to your MCP configuration:
If installed on your machine:
{
"mcpServers": {
"specbridge": {
"command": "specbridge",
"args": ["--specs", "/path/to/your/specs/folder"]
}
}
}
Otherwise:
{
"mcpServers": {
"specbridge": {
"command": "npx",
"args": ["-y", "specbridge", "--specs", "/absolute/path/to/your/specs"]
}
}
}
š» CLI Usage
š Start the server
# Default: stdio transport, current directory
specbridge
# Custom specs folder
specbridge --specs ~/my-api-specs
# HTTP transport mode
specbridge --transport httpStream --port 8080
š List loaded specs and tools
# List all loaded specifications and their tools
specbridge list
# List specs from custom folder
specbridge list --specs ~/my-api-specs
š Authentication Patterns
The server automatically detects authentication from environment variables using these patterns:
Pattern | Auth Type | Usage |
| šļø API Key |
header |
| š« Bearer Token |
|
| š« Bearer Token |
|
+
| š¤ Basic Auth |
|
The {API_NAME} is derived from the filename of your OpenAPI spec:
petstore.jsonāPETSTORE_API_KEYgithub-api.yamlāGITHUB_TOKENmy_custom_api.ymlāMYCUSTOMAPI_API_KEY
š·ļø Tool Naming
Tools are automatically named using this pattern:
With operationId:
{api_name}_{operationId}Without operationId:
{api_name}_{method}_{path_segments}
Examples:
petstore_getPetById(from operationId)github_get_user_repos(generated fromGET /user/repos)
š File Structure
your-project/
āāā api-specs/ # Your OpenAPI specs folder
ā āāā .env # Authentication credentials
ā āāā petstore.json # OpenAPI spec files
ā āāā github.yaml #
ā āāā custom-api.yml #
āāā mcp-config.json # MCP client configuration
š Example OpenAPI Spec
Here's a minimal example that creates two tools:
# ~/mcp-apis/example.yaml
openapi: 3.0.0
info:
title: Example API
version: 1.0.0
servers:
- url: https://api.example.com
paths:
/users/{id}:
get:
operationId: getUser
summary: Get user by ID
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: User found
/users:
post:
operationId: createUser
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
email:
type: string
responses:
'201':
description: User created
This creates tools named:
example_getUserexample_createUser
š§ Troubleshooting
ā No tools appearing?
Check that your OpenAPI specs are valid:
specbridge list --specs /path/to/specsEnsure files have correct extensions (
.json,.yaml,.yml)Check the server logs for parsing errors
ā ļø Note: Specbridge works best when you use absolute paths (with no spaces) for the
--specsargument and other file paths. Relative paths or paths containing spaces may cause issues on some platforms or with some MCP clients.
š Authentication not working?
Verify your
.envfile is in the specs directoryCheck the naming pattern matches your spec filename
Use the list command to verify auth configuration:
specbridge list
š Tools not updating after spec changes?
Restart the MCP server to reload the specs
Check file permissions
Restart the MCP client if needed
š ļø Development
# Clone and install
git clone https://github.com/TBosak/specbridge.git
cd specbridge
npm install
# Build
npm run build
# Test locally
npm run dev -- --specs ./examples
š¤ Contributing
Contributions are welcome! Please feel free to submit issues and pull requests.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
An MCP server that automatically converts OpenAPI specifications into MCP tools by scanning a folder for spec files, requiring no configuration files or separate servers.
Related MCP Servers
- -security-license-qualityGenerate an MCP server for any OpenAPI documented endpoint.Last updated -303MIT License
- -security-license-qualityA command-line tool that transforms any OpenAPI service into a Model Context Protocol (MCP) server, enabling seamless integration with AI agents and tools that support the MCP specification.Last updated -735MIT License
- -security-license-qualityA tool that accelerates MCP protocol adoption by automatically generating MCP-compatible server components from OpenAPI specifications, enabling seamless integration with existing services as a sidecar.Last updated -4