Skip to content

shibbirmcc/kong-ratelimiter-mcp-server

BranchesTags

Repository files navigation

Kong Rate Limiter MCP Server

Build Status Coverage Release Docker Python License

A Model Context Protocol (MCP) server for Kong configuration management, built with FastMCP and Server-Sent Events (SSE) transport. This server provides tools for managing Kong services, routes, and other configuration elements through a standardized MCP interface.

Features

  • FastMCP Integration: Built using the FastMCP SDK for efficient MCP server implementation
  • SSE Transport: Uses Server-Sent Events for real-time communication with MCP clients
  • Modular Architecture: Tools are organized in separate modules for easy extension
  • JSON Configuration: External JSON configuration for tool management
  • Comprehensive Testing: Unit and integration tests with high coverage
  • Kong HTTP Client: HTTP client for Kong Admin API communication with authentication support
  • Extensible Design: Easy to add new Kong configuration tools

Quick Start

Option 1: Virtual Environment Script (Recommended)

./venv.sh                                    # Setup and activate
python -m kong_mcp_server.server            # Run server
pytest --cov=kong_mcp_server                # Run tests with coverage
./venv.sh deactivate                         # Cleanup

Option 2: Server Management Script

./scripts/server.sh start                    # Start server
./scripts/server.sh status                   # Check status
./scripts/server.sh health                   # Health check
./scripts/server.sh logs                     # View logs
./scripts/server.sh stop                     # Stop server

Option 3: Manual Setup

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .[dev]

# Run server
python -m kong_mcp_server.server

# Run tests
pytest

# Check coverage
pytest --cov=kong_mcp_server

Virtual Environment Script Commands

./venv.sh           # Activate venv and install dependencies (default)
./venv.sh activate  # Same as above
./venv.sh deactivate # Deactivate current virtual environment
./venv.sh clean     # Remove virtual environment directory

Architecture

The MCP server follows a modular architecture:

src/kong_mcp_server/
├── __init__.py              # Package initialization
├── server.py                # Main MCP server implementation
├── tools_config.json        # Tool configuration (external JSON)
└── tools/                   # Tool modules
    ├── __init__.py
    ├── basic.py             # Basic tools (hello_world)
    ├── kong_services.py     # Kong services management
    └── kong_routes.py       # Kong routes management

Tool Configuration

Tools are configured in tools_config.json:

{
  "tools": {
    "hello_world": {
      "name": "hello_world",
      "description": "Simple Hello World tool for testing",
      "module": "kong_mcp_server.tools.basic",
      "function": "hello_world",
      "enabled": true
    },
    "kong_get_services": {
      "name": "kong_get_services",
      "description": "Retrieve Kong services configuration",
      "module": "kong_mcp_server.tools.kong_services",
      "function": "get_services",
      "enabled": false
    }
  }
}

Configuration

Environment Variables

# Server Configuration
export FASTMCP_PORT=8080                     # Server port (default: 8080)
export HOST=127.0.0.1                       # Server host (default: 127.0.0.1)

# Kong Configuration
export KONG_ADMIN_URL=http://localhost:8001  # Kong Admin API URL
export KONG_USERNAME=admin                   # Kong CE username
export KONG_PASSWORD=secret                  # Kong CE password
export KONG_API_TOKEN=token                  # Kong EE API token (alternative)
export KONG_TIMEOUT=30.0                     # Request timeout (seconds)
export KONG_VERIFY_SSL=true                  # SSL verification

Kong Authentication

Community Edition (Username/Password):

export KONG_USERNAME=admin
export KONG_PASSWORD=your-password

Enterprise Edition (API Token):

export KONG_API_TOKEN=your-api-token

Port Configuration Examples

# Use default port 8080 (no environment variable needed)
python -m kong_mcp_server.server
./scripts/server.sh start

# Change to custom port
FASTMCP_PORT=9000 python -m kong_mcp_server.server
FASTMCP_PORT=9000 ./scripts/server.sh start

# Docker with custom port
docker run -p 9000:9000 -e FASTMCP_PORT=9000 kong-mcp-server

Available Tools

  • hello_world: Basic test tool that returns a greeting message
  • Kong Services: CRUD operations for Kong services via HTTP API
    • kong_get_services: Retrieve services
    • kong_create_service: Create new service
    • kong_update_service: Update existing service
    • kong_delete_service: Delete service
  • Kong Routes: CRUD operations for Kong routes via HTTP API
    • kong_get_routes: Retrieve routes
    • kong_create_route: Create new route
    • kong_update_route: Update existing route
    • kong_delete_route: Delete route
  • Kong Plugins: Management and retrieval of Kong plugins with filtering and scoping support
    • kong_get_plugins: Retrieve all plugins with optional filtering and pagination
    • kong_get_plugins_by_service: Retrieve plugins scoped to a specific service
    • kong_get_plugins_by_route: Retrieve plugins scoped to a specific route
    • kong_get_plugins_by_consumer: Retrieve plugins scoped to a specific consumer
  • Kong Rate Limiting: CRUD operations for Kong basic rate limiting plugins (Community Edition)
    • kong_create_rate_limiting_plugin: Create basic rate limiting plugin with support for all scopes (global, service, route, consumer) and time-based limits
    • kong_get_rate_limiting_plugins: Retrieve basic rate limiting plugins with filtering by scope, tags, and pagination support
    • kong_update_rate_limiting_plugin: Update basic rate limiting plugin configuration including limits, policies, and Redis settings
    • kong_delete_rate_limiting_plugin: Delete basic rate limiting plugin by plugin ID
  • Kong Plugin Management: General plugin management operations
    • kong_get_plugin: Get specific plugin by ID with full configuration details
    • kong_get_plugins: Get all plugins with optional filtering by name, scope, tags, and pagination support

Adding New Tools

  1. Create a new module in src/kong_mcp_server/tools/
  2. Implement your tool functions
  3. Add tool configuration to tools_config.json
  4. Set "enabled": true to activate the tool

Testing

The project includes comprehensive test coverage:

# Run all tests
pytest

# Run with coverage
pytest --cov=kong_mcp_server --cov-report=term-missing

# Generate text coverage report
pytest --cov=kong_mcp_server --cov-report=xml
coverage report > coverage.txt

# Integration testing (requires testcontainers)
RUN_LIVE_TESTS=true pytest tests/test_kong_integration.py

Development

Code Quality

# Linting
flake8 src/ tests/

# Type checking
mypy src/

# Formatting
black src/ tests/
isort src/ tests/

Docker Deployment

Running from Docker Hub

The Kong Rate Limiter MCP Server is available on Docker Hub as shibbirmcc/kong-ratelimiter-mcp-server.

Host Configuration

By default, the server binds to 127.0.0.1, which works for local development but may not be accessible when running in Docker. For Docker deployments, especially on Windows, you might need to bind to 0.0.0.0 to allow external access:

# Run with custom host binding
docker run -p 8080:8080 -e FASTMCP_HOST=0.0.0.0 shibbirmcc/kong-ratelimiter-mcp-server

Quick Start with Docker Hub

# Pull and run the latest image with host network
docker run --network host shibbirmcc/kong-ratelimiter-mcp-server

# Run with a specific version
docker run --network host shibbirmcc/kong-ratelimiter-mcp-server:latest

# Run in detached mode with a custom name
docker run -d --network host --name kong-mcp shibbirmcc/kong-ratelimiter-mcp-server

Running with Environment Variables

Configure the server using environment variables to connect to your Kong instance:

# Basic configuration (Kong without authentication)
docker run -d --network host \
  --name kong-mcp \
  -e KONG_ADMIN_URL=http://localhost:8001 \
  shibbirmcc/kong-ratelimiter-mcp-server

# Custom port configuration
docker run -d --network host \
  --name kong-mcp \
  -e HOST=127.0.0.1 \
  -e FASTMCP_PORT=8080 \
  -e KONG_ADMIN_URL=http://localhost:8001 \
  shibbirmcc/kong-ratelimiter-mcp-server

# Full configuration with all options
docker run -d --network host \
  --name kong-mcp \
  -e HOST=0.0.0.0 \
  -e FASTMCP_PORT=8080 \
  -e KONG_ADMIN_URL=http://localhost:8001 \
  -e KONG_TIMEOUT=45.0 \
  -e KONG_VERIFY_SSL=false \
  shibbirmcc/kong-ratelimiter-mcp-server

# Using a different port
docker run -d --network host \
  --name kong-mcp \
  -e FASTMCP_PORT=9000 \
  -e KONG_ADMIN_URL=http://localhost:8001 \
  shibbirmcc/kong-ratelimiter-mcp-server

Kong Enterprise Edition with API Token

If you're using Kong Enterprise Edition with API token authentication:

docker run -d --network host \
  --name kong-mcp \
  -e KONG_ADMIN_URL=http://localhost:8001 \
  -e KONG_API_TOKEN=your-api-token \
  shibbirmcc/kong-ratelimiter-mcp-server

Building the Docker Image Locally

If you want to build the image locally instead of using Docker Hub:

# Build the image
docker build -t kong-mcp-server .

# Or build with a specific tag
docker build -t kong-mcp-server:0.1.2 .

Running Locally Built Image

# Run the container with host network
docker run --network host kong-mcp-server

# Run in detached mode
docker run -d --network host --name kong-mcp kong-mcp-server

# Run with environment variables
docker run --network host -e KONG_ADMIN_URL=http://localhost:8001 kong-mcp-server

Docker Compose

Create a docker-compose.yml file:

version: '3.8'
services:
  kong-mcp-server:
    build: .
    ports:
      - "8080:8080"
    environment:
      - KONG_ADMIN_URL=http://kong:8001
    restart: unless-stopped

Run with Docker Compose:

docker-compose up -d

LLM Agent Configuration

Claude Code Integration

To use this MCP server with Claude Code, add the server configuration to your MCP client:

{
  "mcpServers": {
    "kong-rate-limiter": {
      "disabled": false,
      "timeout": 60,
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Server-Sent Events (SSE) Endpoint

The server exposes an SSE endpoint for real-time communication:

  • Endpoint: http://localhost:8080/sse/
  • Protocol: Server-Sent Events (SSE)
  • Content-Type: text/event-stream

Configuration with Other MCP Clients

For other MCP clients, configure the connection as follows:

# Example configuration
server:
  name: "Kong Rate Limiter MCP Server"
  transport: "sse"
  url: "http://localhost:8080/sse/"
  
tools:
  - hello_world
  - kong_get_services
  - kong_create_service
  # ... other tools as enabled in tools_config.json

Kong Authentication Setup

The server supports two authentication methods for Kong Admin API:

Kong Community Edition (Username/Password)

# Set Kong Admin credentials
export KONG_ADMIN_URL=http://localhost:8001
export KONG_USERNAME=admin
export KONG_PASSWORD=your-password

Kong Enterprise Edition (API Token)

# Set Kong Admin API token
export KONG_ADMIN_URL=http://localhost:8001
export KONG_API_TOKEN=your-api-token

Additional Configuration Options

# Request timeout in seconds (default: 30.0)
export KONG_TIMEOUT=45.0

# SSL certificate verification (default: true)
export KONG_VERIFY_SSL=false

Environment Variables

Configure the server behavior using environment variables:

Kong Configuration

# Kong Admin API URL (default: http://localhost:8001)
export KONG_ADMIN_URL=http://your-kong-instance:8001

# Kong Community Edition authentication
export KONG_USERNAME=admin
export KONG_PASSWORD=your-password

# Kong Enterprise Edition authentication (alternative to username/password)
export KONG_API_TOKEN=your-api-token

# Request timeout in seconds (default: 30.0)
export KONG_TIMEOUT=45.0

# SSL certificate verification (default: true)
export KONG_VERIFY_SSL=false

Server Configuration

# Server port (default: 8080)
export FASTMCP_PORT=8080

# Server host (default: 127.0.0.1)
export HOST=0.0.0.0

Changing the Default Port

The server uses port 8080 by default. You can change this in several ways:

Method 1: Environment Variable

# Set custom port
export FASTMCP_PORT=9000
python -m kong_mcp_server.server

Method 2: Docker Run

# Map to a different host port (container still uses 8080)
docker run -p 9000:8080 kong-mcp-server

# Or change both host and container port
docker run -p 9000:9000 -e FASTMCP_PORT=9000 kong-mcp-server

Method 3: Docker Compose

version: '3.8'
services:
  kong-mcp-server:
    build: .
    ports:
      - "9000:8080"  # Host port 9000, container port 8080
    environment:
      - FASTMCP_PORT=8080    # Keep container port as 8080

Method 4: Server Management Script

# Set port via environment variable
FASTMCP_PORT=9000 ./scripts/server.sh start

Running with Different Configurations

Local Python with Environment Variables

Create a .env file in the project root:

KONG_ADMIN_URL=http://localhost:8001
KONG_USERNAME=admin
KONG_PASSWORD=secret
KONG_TIMEOUT=30.0
KONG_VERIFY_SSL=true

Then run:

# Load environment variables and run
python -m kong_mcp_server.server

Docker with Environment Variables

# Run with Kong Community Edition authentication
docker run -p 8080:8080 \
  -e KONG_ADMIN_URL=http://kong:8001 \
  -e KONG_USERNAME=admin \
  -e KONG_PASSWORD=secret \
  kong-mcp-server

# Run with Kong Enterprise Edition authentication
docker run -p 8080:8080 \
  -e KONG_ADMIN_URL=http://kong:8001 \
  -e KONG_API_TOKEN=your-api-token \
  kong-mcp-server

Docker Compose with Environment File

Create a .env file:

KONG_ADMIN_URL=http://kong:8001
KONG_USERNAME=admin
KONG_PASSWORD=secret

Update docker-compose.yml:

version: '3.8'
services:
  kong-mcp-server:
    build: .
    ports:
      - "8080:8080"
    env_file:
      - .env
    restart: unless-stopped

Custom Tool Configuration

Enable/disable tools by modifying tools_config.json:

# Enable Kong services management
# Set "enabled": true for kong_get_services, kong_create_service, etc.

# Restart the server after configuration changes
docker restart kong-mcp

Testing with MCP Inspector

Installation

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

Testing the Server

# Start the Kong MCP server
python -m kong_mcp_server.server

# In a new terminal, test with MCP Inspector using SSE transport
mcp-inspector --transport sse --server-url http://localhost:8080/sse

# Alternative: Test with HTTP transport (for JSON-RPC requests)
mcp-inspector --transport http --server-url http://localhost:8080/sse/request

Manual Testing with cURL

You can also test the server endpoints manually:

# Test API discovery
curl -X GET http://localhost:8080/api

# Test tools/list endpoint
curl -X POST http://localhost:8080/sse/request \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": "test", "method": "tools/list"}'

# Test tool execution (example: get Kong routes)
curl -X POST http://localhost:8080/sse/request \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": "test", "method": "tools/call", "params": {"name": "kong_get_routes", "arguments": {}}}'

Web Interface

The MCP Inspector provides a web interface for interactive testing:

  1. Run mcp-inspector --transport sse --server-url http://localhost:8080/sse
  2. Open the browser URL displayed in the terminal
  3. Use the web interface to:
    • View all available tools
    • Inspect tool schemas
    • Execute tools with custom parameters
    • Debug responses in real-time

License

Apache 2.0

About

A Rate Limiter MCP Server that will connect to Kong apigateway and update rate limiter configurations

Resources

Readme

License

Apache-2.0 license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.2.0: MCP Protocol Compliance and Enhanced Kong Integration Latest
Aug 23, 2025

Packages

 
 
 

Contributors

Languages