AWS Bedrock Knowledge Base Retrieval MCP server

The Amazon Bedrock Knowledge Base MCP Server provides a seamless way to access and query Amazon Bedrock Knowledge Bases through a standardized interface. It allows you to discover knowledge bases, retrieve information using natural language queries, filter results by data source, and improve result relevance through reranking capabilities.

Prerequisites

Installation Requirements

Before installing the MCP server, you need:

1. Install uv from Astral or the GitHub README
2. Install Python using uv python install 3.10

AWS Configuration

Your AWS environment must be properly configured:

1. AWS CLI Configuration: Configure AWS CLI with credentials and an AWS_PROFILE that has access to Amazon Bedrock and Knowledge Bases
2. Amazon Bedrock Knowledge Base: Have at least one Amazon Bedrock Knowledge Base with the tag key mcp-multirag-kb with a value of true
3. IAM Permissions: Your IAM role/user must have permissions to:
   • List and describe knowledge bases
   • Access data sources
   • Query knowledge bases

Reranking Setup

To use the reranking functionality:

1. Ensure your IAM role has permissions for both bedrock:Rerank and bedrock:InvokeModel actions
2. Verify the Amazon Bedrock Knowledge Bases service role has these permissions
3. Check that you're using a supported region for reranking
4. Enable model access for available reranking models in your region

Installation

Standard Installation

Configure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit ~/.aws/amazonq/mcp.json):

{
  "mcpServers": {
    "awslabs.bedrock-kb-retrieval-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.bedrock-kb-retrieval-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-profile-name",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "KB_INCLUSION_TAG_KEY": "optional-tag-key-to-filter-kbs",
        "BEDROCK_KB_RERANKING_ENABLED": "false"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Docker Installation

If you prefer using Docker, first build the image:

docker build -t awslabs/bedrock-kb-retrieval-mcp-server .

Create a .env file with your AWS credentials:

AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

Then configure your MCP client:

{
  "mcpServers": {
    "awslabs.bedrock-kb-retrieval-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--env",
        "FASTMCP_LOG_LEVEL=ERROR",
        "--env",
        "KB_INCLUSION_TAG_KEY=optional-tag-key-to-filter-kbs",
        "--env",
        "BEDROCK_KB_RERANKING_ENABLED=false",
        "--env",
        "AWS_REGION=us-east-1",
        "--env-file",
        "/full/path/to/file/above/.env",
        "awslabs/bedrock-kb-retrieval-mcp-server:latest"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Note: When using Docker, you'll need to keep your AWS credentials refreshed from your host.

Configuration Options

Environment Variables

The MCP server supports several environment variables:

• AWS_PROFILE: Your AWS profile name with Bedrock access
• AWS_REGION: AWS region to use (e.g., "us-east-1")
• FASTMCP_LOG_LEVEL: Logging level (recommend "ERROR" for production)
• KB_INCLUSION_TAG_KEY: Optional tag key to filter knowledge bases
• BEDROCK_KB_RERANKING_ENABLED: Enable/disable reranking globally
  • For enabling: 'true', '1', 'yes', or 'on' (case-insensitive)
  • For disabling: any other value or not set (default)

Usage Features

Discovering Knowledge Bases

The server allows you to:

• Find and explore all available knowledge bases
• Search for knowledge bases by name or tag
• List data sources associated with each knowledge base

Querying Knowledge Bases

Use natural language to:

• Retrieve information with conversational queries
• Get relevant passages from your knowledge bases
• Access citation information for all results

Filtering Results

Focus your queries by:

• Targeting specific data sources
• Including or excluding particular sources
• Prioritizing results from specific sources

Reranking Results

Improve retrieval relevance by:

• Using Amazon Bedrock reranking capabilities
• Sorting results by relevance to your query

Limitations

• Results with IMAGE content type are not included in KB query responses
• Reranking requires specific permissions, model access, and is only available in certain regions

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "awslabs-bedrock-kb-retrieval-mcp-server" '{"command":"uvx","args":["awslabs.bedrock-kb-retrieval-mcp-server@latest"],"env":{"AWS_PROFILE":"your-profile-name","AWS_REGION":"us-east-1","FASTMCP_LOG_LEVEL":"ERROR","KB_INCLUSION_TAG_KEY":"optional-tag-key-to-filter-kbs","BEDROCK_KB_RERANKING_ENABLED":"false"},"disabled":false,"autoApprove":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "awslabs.bedrock-kb-retrieval-mcp-server": {
            "command": "uvx",
            "args": [
                "awslabs.bedrock-kb-retrieval-mcp-server@latest"
            ],
            "env": {
                "AWS_PROFILE": "your-profile-name",
                "AWS_REGION": "us-east-1",
                "FASTMCP_LOG_LEVEL": "ERROR",
                "KB_INCLUSION_TAG_KEY": "optional-tag-key-to-filter-kbs",
                "BEDROCK_KB_RERANKING_ENABLED": "false"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "awslabs.bedrock-kb-retrieval-mcp-server": {
            "command": "uvx",
            "args": [
                "awslabs.bedrock-kb-retrieval-mcp-server@latest"
            ],
            "env": {
                "AWS_PROFILE": "your-profile-name",
                "AWS_REGION": "us-east-1",
                "FASTMCP_LOG_LEVEL": "ERROR",
                "KB_INCLUSION_TAG_KEY": "optional-tag-key-to-filter-kbs",
                "BEDROCK_KB_RERANKING_ENABLED": "false"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

3. Restart Claude Desktop for the changes to take effect