mcp/api-gateway

A universal MCP (Model Context Protocol) server to integrate any API with Claude Desktop using only Docker configurations.

Quick Installation

1. Using Docker Hub (Recommended)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-api": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--pull", "always",
        "-e", "API_1_NAME=my-api",
        "-e", "API_1_SWAGGER_URL=https://api.example.com/swagger.json",
        "-e", "API_1_BASE_URL=https://api.example.com/v1",
        "-e", "API_1_HEADER_AUTHORIZATION=Bearer YOUR_TOKEN",
        "rflpazini/mcp-api-gateway:latest"
      ]
    }
  }
}

2. Local Build

# Clone the repository
git clone https://github.com/rflpazini/mcp-api-gateway
cd mcp-api-gateway

# Build the image
docker build -t mcp-api-gateway .

# Local test
docker run --rm -it \
  -e API_1_NAME=test \
  -e API_1_SWAGGER_URL=https://petstore.swagger.io/v2/swagger.json \
  -e API_1_BASE_URL=https://petstore.swagger.io/v2 \
  mcp-api-gateway

API Configuration

Environment Variables

Variable	Description	Required
API_N_NAME	Unique API name	Yes
API_N_SWAGGER_URL	Swagger/OpenAPI file URL	Yes
API_N_BASE_URL	API base URL (overrides Swagger)	No
API_N_HEADER_*	Custom headers	No
API_N_HEADERS	JSON with multiple headers	No

Configuration Examples

Simple API with Authentication

{
  "mcpServers": {
    "github-api": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "API_1_NAME=github",
        "-e", "API_1_SWAGGER_URL=https://api.github.com/swagger.json",
        "-e", "API_1_HEADER_AUTHORIZATION=token ghp_xxxxxxxxxxxx",
        "mcp-api-gateway:latest"
      ]
    }
  }
}

Multiple APIs

{
  "mcpServers": {
    "company-apis": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        // Users API
        "-e", "API_1_NAME=users",
        "-e", "API_1_SWAGGER_URL=https://api.company.com/users/swagger.json",
        "-e", "API_1_HEADER_X_API_KEY=users_key_123",
        
        // Products API  
        "-e", "API_2_NAME=products",
        "-e", "API_2_SWAGGER_URL=https://api.company.com/products/openapi.yaml",
        "-e", "API_2_HEADER_AUTHORIZATION=Bearer products_token",
        
        // Orders API (with multiple headers)
        "-e", "API_3_NAME=orders",
        "-e", "API_3_SWAGGER_URL=https://api.company.com/orders/spec.json",
        "-e", "API_3_HEADERS={\"Authorization\":\"Bearer token\",\"X-Tenant\":\"company123\"}",
        
        "mcp-api-gateway:latest"
      ]
    }
  }
}

Using in Claude

Available Commands

1. View available APIs

   • "What APIs are configured?"
   • "Show me the available endpoints"

2. Explore endpoints

   • "How do I create a user?"
   • "What parameters do I need to search for products?"

3. Execute operations

   • "Create a user named John with email [email protected]"
   • "List all orders from today"
   • "Update product ID 123 with new price $99.90"

Conversation Examples

You: "Create a new customer named Mary Smith"

Claude: "I'll create the customer for you. Using the customers API..."

{
  "id": "12345",
  "name": "Mary Smith",
  "createdAt": "2024-01-15T10:30:00Z"
}

"Customer Mary Smith created successfully! ID: 12345"

Publishing to Docker Hub

# Build for multiple architectures
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t your-username/mcp-api-gateway:latest \
  -t your-username/mcp-api-gateway:1.0.0 \
  --push .

Use Cases

1. Internal Company API

"-e", "API_1_NAME=erp",
"-e", "API_1_SWAGGER_URL=https://erp.company.local/api/swagger.json",
"-e", "API_1_BASE_URL=https://erp.company.local/api",
"-e", "API_1_HEADER_X_COMPANY_ID=company123",
"-e", "API_1_HEADER_AUTHORIZATION=Bearer internal_token"

2. API with Local Swagger

// Mount local Swagger file
"-v", "/path/to/swagger.yaml:/swagger.yaml",
"-e", "API_1_NAME=local-api",
"-e", "API_1_SWAGGER_URL=file:///swagger.yaml",
"-e", "API_1_BASE_URL=http://localhost:3000"

3. GraphQL API (via REST wrapper)

"-e", "API_1_NAME=graphql",
"-e", "API_1_SWAGGER_URL=https://api.example.com/graphql-swagger.json",
"-e", "API_1_BASE_URL=https://api.example.com/graphql"

Security

Best Practices

1. Never commit tokens: Use environment variables or secrets
2. Use limited scope tokens: Only necessary permissions
3. Rotate tokens regularly: Update your tokens periodically
4. Always use HTTPS: Ensure your APIs use HTTPS

Example with Docker Secrets

# Create the secret
echo "your_token_here" | docker secret create api_token -

# Use in claude_desktop_config.json
"args": [
  "run", "--rm", "-i",
  "-e", "API_1_HEADER_AUTHORIZATION=Bearer $(cat /run/secrets/api_token)",
  "--secret", "api_token",
  "mcp-api-gateway:latest"
]

Troubleshooting

API not showing up

• Check if the Swagger URL is accessible
• Confirm environment variables are correct
• Check logs: docker logs <container_id>

Authentication error

• Verify token is correct
• Confirm header format (Bearer, Basic, etc)
• Test the API directly first

Slow performance

• Use --pull always only the first time
• Consider caching the image locally
• Check API latency

Contributing

PRs are welcome! Some ideas:

• OAuth authentication support
• Smart response caching
• WebSocket support
• Web configuration interface
• Metrics and observability

License

MIT License - see LICENSE file for details.