Features

• Dual Transport - STDIO for Claude Desktop, Streamable HTTP for ChatGPT
• Smart Filtering - Schema-driven where constraints + raw Bedrock filters + implicit filtering
• Reranking - Optional AMAZON or COHERE reranking for improved relevance
• Auto Schema Discovery - Automatically infer metadata schemas from retrieval results
• OAuth Support - Auth0 integration for secure ChatGPT connections
• Read-Only - Safe by design; no write operations to your knowledge bases

Architecture

Quick Start

Claude Desktop (STDIO)

Add to your Claude Desktop config:

{
  "mcpServers": {
    "bedrock-kb": {
      "command": "uvx",
      "args": ["amazon-bedrock-knowledge-base-mcp"],
      "env": {
        "AWS_PROFILE": "your-profile",
        "AWS_REGION": "us-west-2"
      }
    }
  }
}

ChatGPT (Streamable HTTP)

AWS_PROFILE=your-profile \
AWS_REGION=us-west-2 \
MCP_TRANSPORT=streamable-http \
uvx amazon-bedrock-knowledge-base-mcp

Then configure ChatGPT to connect to https://your-domain.example.com/mcp.

Note: ChatGPT requires HTTPS. Use a tunnel (ngrok, Cloudflare Tunnel) for local testing.

Available Tools

Discovery Tools

Query Tools

Recommended Workflow

1. List - Call ListKnowledgeBases to find available knowledge bases
2. Explore - Use QueryKnowledgeBasesWithMetadata to discover metadata keys/values
3. Schema - Call DescribeMetadataSchema to see available filter fields
4. Query - Use QueryKnowledgeBases with where filters for precise retrieval

Environment Variables

AWS Configuration

*Either AWS_PROFILE or IAM role credentials are required.

Knowledge Base Discovery

Retrieval Defaults

Filtering

HTTP Server (Streamable HTTP only)

OAuth (Auth0)

*Required when MCP_AUTH_MODE=oauth

Logging

Documentation

Docker

# Build the image
docker build -t amazon-bedrock-knowledge-base-mcp:local .

# Run with AWS credentials
docker run --rm \
  -v "$HOME/.aws:/home/app/.aws:ro" \
  -e AWS_PROFILE=your-profile \
  -e AWS_REGION=us-west-2 \
  amazon-bedrock-knowledge-base-mcp:local

# Run as HTTP server
docker run --rm \
  -p 8000:8000 \
  -v "$HOME/.aws:/home/app/.aws:ro" \
  -e AWS_PROFILE=your-profile \
  -e AWS_REGION=us-west-2 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  amazon-bedrock-knowledge-base-mcp:local

Health Endpoints

Development

# Clone and install
git clone https://github.com/Zlash65/amazon-bedrock-knowledge-base-mcp.git
cd amazon-bedrock-knowledge-base-mcp
uv sync --group dev

# Run tests
uv run pytest -q

# Type check
uv run pyright

# Lint
uv run ruff check .

# Format
uv run ruff format .

Metadata Schema

Schema files define available metadata fields for filtering. See schemas/README.md for examples.

Example schema:

{
  "fields": [
    {
      "key": "x-amz-bedrock-kb-source-uri",
      "type": "string",
      "description": "Source document URI",
      "alias": "source"
    },
    {
      "key": "category",
      "type": "string",
      "description": "Document category",
      "filterable": true
    }
  ]
}

Use in queries:

# Using alias
{"where": {"source": "s3://bucket/doc.pdf"}}

# Using direct key
{"where": {"category": ["finance", "legal"]}}

Limitations

• Results with IMAGE content type are not included in query responses
• Reranking requires additional IAM permissions and is only available in specific regions
• Knowledge bases must be tagged with KB_INCLUSION_TAG_KEY=true to be discoverable

License

Apache-2.0 - see LICENSE and NOTICE.