AWS Labs Bedrock KB Retrieval MCP Server

1.0.19 · active · verified Fri Apr 17

The `awslabs-bedrock-kb-retrieval-mcp-server` library provides an AWS Labs Model Context Protocol (MCP) server specifically designed for integrating with Amazon Bedrock Knowledge Bases. It allows other MCP-compliant applications to retrieve information from a Bedrock Knowledge Base via a standard HTTP API. As part of the AWS Labs ecosystem, it typically receives updates driven by Bedrock feature enhancements and MCP protocol evolution, currently at version 1.0.19.

Common errors

```
botocore.exceptions.ClientError: An error occurred (AccessDeniedException) when calling the Retrieve operation:
```
cause The IAM role/user running the server lacks necessary permissions to perform Bedrock Knowledge Base retrieval.

fix Grant `bedrock:Retrieve` and potentially `s3:GetObject` (if KB data source is S3) permissions to the AWS principal running the server for the target Bedrock Knowledge Base and S3 bucket.
```
botocore.exceptions.ClientError: An error occurred (ResourceNotFoundException) when calling the Retrieve operation:
```
cause The provided `knowledge_base_id` does not exist, is invalid, or is not available in the specified `region_name`.

fix Double-check the Bedrock Knowledge Base ID and the AWS region name. Ensure the KB is active and correctly configured in the Bedrock console.
```
ModuleNotFoundError: No module named 'bedrock_kb_retrieval_mcp_server'
```
cause The `awslabs-bedrock-kb-retrieval-mcp-server` package is not installed in the current Python environment, or the import path is incorrect.

fix Install the package using `pip install awslabs-bedrock-kb-retrieval-mcp-server`. Verify that the import statement `from bedrock_kb_retrieval_mcp_server.server import BedrockKBRetrievalMCPServer` is correct.
```
uvicorn.config.ConfigError: Provided target must be an ASGI application, e.g. 'main:app'.
```
cause The `uvicorn.run()` function was not provided with the correct ASGI application object, or `server.get_fastapi_app()` did not return an app.

fix Ensure `fastapi_app = server.get_fastapi_app()` is correctly called and its result is passed to `uvicorn.run(fastapi_app, ...)`. The quickstart code snippet demonstrates the correct pattern.

Warnings

gotcha Incorrect AWS IAM Permissions: The server requires appropriate IAM permissions to interact with Bedrock Knowledge Bases and associated resources (e.g., S3 buckets for data sources).
Fix: Ensure the AWS principal (user/role) running the server has `bedrock:Retrieve`, `bedrock:InvokeModel` (if using custom models), and `s3:GetObject` (for any S3 buckets used by the knowledge base) permissions for the relevant resources.
gotcha Invalid or Mismatched Knowledge Base ID/Region: Providing a Knowledge Base ID that does not exist, is in a different region, or is not accessible can lead to `ResourceNotFoundException` errors.
Fix: Verify that the `knowledge_base_id` and `region_name` provided to `BedrockKBRetrievalMCPServer` constructor are correct and correspond to an accessible Bedrock Knowledge Base in the specified region. Check the Bedrock console for the exact ID and region.
gotcha AWS Credentials Not Found or Expired: The `boto3` library used internally relies on standard AWS credential provider chain. If credentials are missing, malformed, or expired, the server will fail to connect to AWS services.
Fix: Ensure AWS credentials (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) are correctly set as environment variables, or configured in `~/.aws/credentials` or IAM instance profiles/roles for EC2/ECS/EKS deployments.

Install

pip install awslabs-bedrock-kb-retrieval-mcp-server Install stable version

Imports

BedrockKBRetrievalMCPServer

from bedrock_kb_retrieval_mcp_server.server import BedrockKBRetrievalMCPServer

Quickstart

This quickstart demonstrates how to instantiate and run the `BedrockKBRetrievalMCPServer` using Uvicorn. It requires AWS credentials configured in the environment or AWS shared credentials file, and a valid Amazon Bedrock Knowledge Base ID. The server will expose an HTTP endpoint for MCP retrieval requests.

import os
import uvicorn
from bedrock_kb_retrieval_mcp_server.server import BedrockKBRetrievalMCPServer

# --- Configuration --- #
# Ensure AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION are set in your environment
# or via ~/.aws/credentials. You also need a Bedrock Knowledge Base ID.
KNOWLEDGE_BASE_ID = os.environ.get("BEDROCK_KB_ID", "YOUR_KNOWLEDGE_BASE_ID")
REGION_NAME = os.environ.get("AWS_REGION", "us-east-1") # e.g., 'us-east-1', 'us-west-2'

if KNOWLEDGE_BASE_ID == "YOUR_KNOWLEDGE_BASE_ID":
    print("WARNING: BEDROCK_KB_ID environment variable not set. Using placeholder.")
    print("Please set BEDROCK_KB_ID to a valid Amazon Bedrock Knowledge Base ID.")
    exit(1)

print(f"Initializing Bedrock KB Retrieval MCP Server for KB ID: {KNOWLEDGE_BASE_ID}")
print(f"In AWS Region: {REGION_NAME}")

# Initialize the server instance
try:
    server = BedrockKBRetrievalMCPServer(
        knowledge_base_id=KNOWLEDGE_BASE_ID,
        region_name=REGION_NAME
    )
    # Get the FastAPI application instance
    fastapi_app = server.get_fastapi_app()

    # Run the server using Uvicorn
    # The server will be accessible at http://127.0.0.1:8000
    if __name__ == "__main__":
        print("Starting Uvicorn server on http://127.0.0.1:8000")
        uvicorn.run(fastapi_app, host="127.0.0.1", port=8000)

except Exception as e:
    print(f"Error initializing or running server: {e}")
    print("Ensure AWS credentials, region, and Bedrock Knowledge Base ID are correctly configured.")

view raw JSON →