Specbridge

Verified on MseeP smithery badge

Built with FastMCP for TypeScript.

✨ Features

🎯 Zero Configuration: Filesystem is the interface - just drop OpenAPI specs in a folder
🔐 Auto Authentication: Simple .env file with {API_NAME}_API_KEY pattern
🏷️ 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_NAME}_API_KEY`	🗝️ API Key	`X-API-Key` header
`{API_NAME}_TOKEN`	🎫 Bearer Token	`Authorization: Bearer {token}`
`{API_NAME}_BEARER_TOKEN`	🎫 Bearer Token	`Authorization: Bearer {token}`
`{API_NAME}_USERNAME` + `{API_NAME}_PASSWORD`	👤 Basic Auth	`Authorization: Basic {base64}`

The {API_NAME} is derived from the filename of your OpenAPI spec:

petstore.json → PETSTORE_API_KEY
github-api.yaml → GITHUB_TOKEN
my_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 from GET /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_getUser
example_createUser

🔧 Troubleshooting

❌ No tools appearing?

Check that your OpenAPI specs are valid:
specbridge list --specs /path/to/specs
Ensure 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 --specs argument 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 .env file is in the specs directory
Check 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.