# Amazon Bedrock Knowledge Base Retrieval MCP Server
MCP server for accessing Amazon Bedrock Knowledge Bases
## Features
### Discover knowledge bases and their data sources
- Find and explore all available knowledge bases
- Search for knowledge bases by name or tag
- List data sources associated with each knowledge base
### Query knowledge bases with natural language
- Retrieve information using conversational queries
- Get relevant passages from your knowledge bases
- Access citation information for all results
### Filter results by data source
- Focus your queries on specific data sources
- Include or exclude specific data sources
- Prioritize results from specific data sources
### Rerank results
- Improve relevance of retrieval results
- Use Amazon Bedrock reranking capabilities
- Sort results by relevance to your query
## Prerequisites
### Installation Requirements
1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
2. Install Python using `uv python install 3.10`
### AWS Requirements
1. **AWS CLI Configuration**: You must have the AWS CLI configured with credentials and an AWS_PROFILE that has access to Amazon Bedrock and Knowledge Bases
2. **Amazon Bedrock Knowledge Base**: You must 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 appropriate permissions to:
- List and describe knowledge bases
- Access data sources
- Query knowledge bases
### Reranking Requirements
If you intend to use reranking functionality, your Bedrock Knowledge Base needs additional permissions:
1. Your IAM role must have permissions for both `bedrock:Rerank` and `bedrock:InvokeModel` actions
2. The Amazon Bedrock Knowledge Bases service role must also have these permissions
3. Reranking is only available in specific regions. Please refer to the official [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/rerank-supported.html) for an up to date list of supported regions.
4. Enable model access for the available reranking models in the specified region.
### Controlling Reranking
Reranking can be globally enabled or disabled using the `BEDROCK_KB_RERANKING_ENABLED` environment variable:
- Set to `false` (default): Disables reranking for all queries unless explicitly enabled
- Set to `true`: Enables reranking for all queries unless explicitly disabled
The environment variable accepts various formats:
- For enabling: 'true', '1', 'yes', or 'on' (case-insensitive)
- For disabling: any other value or not set (default behavior)
This setting provides a global default, while individual API calls can still override it by explicitly setting the `reranking` parameter.
For detailed instructions on setting up knowledge bases, see:
- [Create a knowledge base](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-create.html)
- [Managing permissions for Amazon Bedrock knowledge bases](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-prereq-permissions-general.html)
- [Permissions for reranking in Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/rerank-prereq.html)
## Installation
| Cursor | VS Code |
|:------:|:-------:|
| [](https://cursor.com/en/install-mcp?name=awslabs.bedrock-kb-retrieval-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMuYmVkcm9jay1rYi1yZXRyaWV2YWwtbWNwLXNlcnZlckBsYXRlc3QiLCJlbnYiOnsiQVdTX1BST0ZJTEUiOiJ5b3VyLXByb2ZpbGUtbmFtZSIsIkFXU19SRUdJT04iOiJ1cy1lYXN0LTEiLCJGQVNUTUNQX0xPR19MRVZFTCI6IkVSUk9SIiwiS0JfSU5DTFVTSU9OX1RBR19LRVkiOiJvcHRpb25hbC10YWcta2V5LXRvLWZpbHRlci1rYnMiLCJCRURST0NLX0tCX1JFUkFOS0lOR19FTkFCTEVEIjoiZmFsc2UifSwiZGlzYWJsZWQiOmZhbHNlLCJhdXRvQXBwcm92ZSI6W119) | [](https://insiders.vscode.dev/redirect/mcp/install?name=Bedrock%20KB%20Retrieval%20MCP%20Server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.bedrock-kb-retrieval-mcp-server%40latest%22%5D%2C%22env%22%3A%7B%22AWS_PROFILE%22%3A%22your-profile-name%22%2C%22AWS_REGION%22%3A%22us-east-1%22%2C%22FASTMCP_LOG_LEVEL%22%3A%22ERROR%22%2C%22KB_INCLUSION_TAG_KEY%22%3A%22optional-tag-key-to-filter-kbs%22%2C%22BEDROCK_KB_RERANKING_ENABLED%22%3A%22false%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D) |
Configure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):
```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": []
}
}
}
```
### Windows Installation
For Windows users, the MCP server configuration format is slightly different:
```json
{
"mcpServers": {
"awslabs.bedrock-kb-retrieval-mcp-server": {
"disabled": false,
"timeout": 60,
"type": "stdio",
"command": "uv",
"args": [
"tool",
"run",
"--from",
"awslabs.bedrock-kb-retrieval-mcp-server@latest",
"awslabs.bedrock-kb-retrieval-mcp-server.exe"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR",
"AWS_PROFILE": "your-aws-profile",
"AWS_REGION": "us-east-1"
}
}
}
}
```
or docker after a successful `docker build -t awslabs/bedrock-kb-retrieval-mcp-server .`:
```file
# fictitious `.env` file with AWS temporary credentials
AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk
```
```json
{
"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: Your credentials will need to be kept refreshed from your host
## Limitations
- Results with `IMAGE` content type are not included in the KB query response.
- The `reranking` parameter requires additional permissions, Amazon Bedrock model access, and is only available in specific regions.
Raw data
{
"_id": null,
"home_page": null,
"name": "awslabs.bedrock-kb-retrieval-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Amazon Web Services",
"author_email": "AWSLabs MCP <203918161+awslabs-mcp@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/9b/21/c80aad2a787fdd90e0ea368fa378d0ae80d8162e5d246fd850465eea3565/awslabs_bedrock_kb_retrieval_mcp_server-1.0.8.tar.gz",
"platform": null,
"description": "# Amazon Bedrock Knowledge Base Retrieval MCP Server\n\nMCP server for accessing Amazon Bedrock Knowledge Bases\n\n## Features\n\n### Discover knowledge bases and their data sources\n\n- Find and explore all available knowledge bases\n- Search for knowledge bases by name or tag\n- List data sources associated with each knowledge base\n\n### Query knowledge bases with natural language\n\n- Retrieve information using conversational queries\n- Get relevant passages from your knowledge bases\n- Access citation information for all results\n\n### Filter results by data source\n\n- Focus your queries on specific data sources\n- Include or exclude specific data sources\n- Prioritize results from specific data sources\n\n### Rerank results\n\n- Improve relevance of retrieval results\n- Use Amazon Bedrock reranking capabilities\n- Sort results by relevance to your query\n\n## Prerequisites\n\n### Installation Requirements\n\n1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)\n2. Install Python using `uv python install 3.10`\n\n### AWS Requirements\n\n1. **AWS CLI Configuration**: You must have the AWS CLI configured with credentials and an AWS_PROFILE that has access to Amazon Bedrock and Knowledge Bases\n2. **Amazon Bedrock Knowledge Base**: You must have at least one Amazon Bedrock Knowledge Base with the tag key `mcp-multirag-kb` with a value of `true`\n3. **IAM Permissions**: Your IAM role/user must have appropriate permissions to:\n - List and describe knowledge bases\n - Access data sources\n - Query knowledge bases\n\n### Reranking Requirements\n\nIf you intend to use reranking functionality, your Bedrock Knowledge Base needs additional permissions:\n\n1. Your IAM role must have permissions for both `bedrock:Rerank` and `bedrock:InvokeModel` actions\n2. The Amazon Bedrock Knowledge Bases service role must also have these permissions\n3. Reranking is only available in specific regions. Please refer to the official [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/rerank-supported.html) for an up to date list of supported regions.\n4. Enable model access for the available reranking models in the specified region.\n\n### Controlling Reranking\n\nReranking can be globally enabled or disabled using the `BEDROCK_KB_RERANKING_ENABLED` environment variable:\n\n- Set to `false` (default): Disables reranking for all queries unless explicitly enabled\n- Set to `true`: Enables reranking for all queries unless explicitly disabled\n\nThe environment variable accepts various formats:\n\n- For enabling: 'true', '1', 'yes', or 'on' (case-insensitive)\n- For disabling: any other value or not set (default behavior)\n\nThis setting provides a global default, while individual API calls can still override it by explicitly setting the `reranking` parameter.\n\nFor detailed instructions on setting up knowledge bases, see:\n\n- [Create a knowledge base](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-create.html)\n- [Managing permissions for Amazon Bedrock knowledge bases](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-prereq-permissions-general.html)\n- [Permissions for reranking in Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/rerank-prereq.html)\n\n## Installation\n\n| Cursor | VS Code |\n|:------:|:-------:|\n| [](https://cursor.com/en/install-mcp?name=awslabs.bedrock-kb-retrieval-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMuYmVkcm9jay1rYi1yZXRyaWV2YWwtbWNwLXNlcnZlckBsYXRlc3QiLCJlbnYiOnsiQVdTX1BST0ZJTEUiOiJ5b3VyLXByb2ZpbGUtbmFtZSIsIkFXU19SRUdJT04iOiJ1cy1lYXN0LTEiLCJGQVNUTUNQX0xPR19MRVZFTCI6IkVSUk9SIiwiS0JfSU5DTFVTSU9OX1RBR19LRVkiOiJvcHRpb25hbC10YWcta2V5LXRvLWZpbHRlci1rYnMiLCJCRURST0NLX0tCX1JFUkFOS0lOR19FTkFCTEVEIjoiZmFsc2UifSwiZGlzYWJsZWQiOmZhbHNlLCJhdXRvQXBwcm92ZSI6W119) | [](https://insiders.vscode.dev/redirect/mcp/install?name=Bedrock%20KB%20Retrieval%20MCP%20Server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.bedrock-kb-retrieval-mcp-server%40latest%22%5D%2C%22env%22%3A%7B%22AWS_PROFILE%22%3A%22your-profile-name%22%2C%22AWS_REGION%22%3A%22us-east-1%22%2C%22FASTMCP_LOG_LEVEL%22%3A%22ERROR%22%2C%22KB_INCLUSION_TAG_KEY%22%3A%22optional-tag-key-to-filter-kbs%22%2C%22BEDROCK_KB_RERANKING_ENABLED%22%3A%22false%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D) |\n\nConfigure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"awslabs.bedrock-kb-retrieval-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"awslabs.bedrock-kb-retrieval-mcp-server@latest\"],\n \"env\": {\n \"AWS_PROFILE\": \"your-profile-name\",\n \"AWS_REGION\": \"us-east-1\",\n \"FASTMCP_LOG_LEVEL\": \"ERROR\",\n \"KB_INCLUSION_TAG_KEY\": \"optional-tag-key-to-filter-kbs\",\n \"BEDROCK_KB_RERANKING_ENABLED\": \"false\"\n },\n \"disabled\": false,\n \"autoApprove\": []\n }\n }\n}\n```\n### Windows Installation\n\nFor Windows users, the MCP server configuration format is slightly different:\n\n```json\n{\n \"mcpServers\": {\n \"awslabs.bedrock-kb-retrieval-mcp-server\": {\n \"disabled\": false,\n \"timeout\": 60,\n \"type\": \"stdio\",\n \"command\": \"uv\",\n \"args\": [\n \"tool\",\n \"run\",\n \"--from\",\n \"awslabs.bedrock-kb-retrieval-mcp-server@latest\",\n \"awslabs.bedrock-kb-retrieval-mcp-server.exe\"\n ],\n \"env\": {\n \"FASTMCP_LOG_LEVEL\": \"ERROR\",\n \"AWS_PROFILE\": \"your-aws-profile\",\n \"AWS_REGION\": \"us-east-1\"\n }\n }\n }\n}\n```\n\n\nor docker after a successful `docker build -t awslabs/bedrock-kb-retrieval-mcp-server .`:\n\n```file\n# fictitious `.env` file with AWS temporary credentials\nAWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE\nAWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\nAWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk\n```\n\n```json\n {\n \"mcpServers\": {\n \"awslabs.bedrock-kb-retrieval-mcp-server\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"--interactive\",\n \"--env\",\n \"FASTMCP_LOG_LEVEL=ERROR\",\n \"--env\",\n \"KB_INCLUSION_TAG_KEY=optional-tag-key-to-filter-kbs\",\n \"--env\",\n \"BEDROCK_KB_RERANKING_ENABLED=false\",\n \"--env\",\n \"AWS_REGION=us-east-1\",\n \"--env-file\",\n \"/full/path/to/file/above/.env\",\n \"awslabs/bedrock-kb-retrieval-mcp-server:latest\"\n ],\n \"env\": {},\n \"disabled\": false,\n \"autoApprove\": []\n }\n }\n }\n```\n\nNOTE: Your credentials will need to be kept refreshed from your host\n\n## Limitations\n\n- Results with `IMAGE` content type are not included in the KB query response.\n- The `reranking` parameter requires additional permissions, Amazon Bedrock model access, and is only available in specific regions.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "An AWS Labs Model Context Protocol (MCP) server for Bedrock Knowledge Base Retrieval",
"version": "1.0.8",
"project_urls": {
"Bug Tracker": "https://github.com/awslabs/mcp/issues",
"Changelog": "https://github.com/awslabs/mcp/blob/main/src/bedrock-kb-retrieval-mcp-server/CHANGELOG.md",
"Documentation": "https://awslabs.github.io/mcp/servers/bedrock-kb-retrieval-mcp-server/",
"Homepage": "https://awslabs.github.io/mcp/",
"Source": "https://github.com/awslabs/mcp.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4528d062d79bd9472485bd27e1d3a0cb9c17f0b7eeacde9294808211829e15fe",
"md5": "f74e411fe93978d1cfcd7530bfd1260e",
"sha256": "96a29ee83b205ea6e4a99091bac4853c7366a8e514c7b01f4f2dddcbddf77c2d"
},
"downloads": -1,
"filename": "awslabs_bedrock_kb_retrieval_mcp_server-1.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f74e411fe93978d1cfcd7530bfd1260e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 18977,
"upload_time": "2025-10-13T20:49:31",
"upload_time_iso_8601": "2025-10-13T20:49:31.629850Z",
"url": "https://files.pythonhosted.org/packages/45/28/d062d79bd9472485bd27e1d3a0cb9c17f0b7eeacde9294808211829e15fe/awslabs_bedrock_kb_retrieval_mcp_server-1.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9b21c80aad2a787fdd90e0ea368fa378d0ae80d8162e5d246fd850465eea3565",
"md5": "aea1999e19cdf9f14bccf21743d82605",
"sha256": "72a42fb86960e342547980f1073993a6f15c412bac58b4f8d17cad3a81927f40"
},
"downloads": -1,
"filename": "awslabs_bedrock_kb_retrieval_mcp_server-1.0.8.tar.gz",
"has_sig": false,
"md5_digest": "aea1999e19cdf9f14bccf21743d82605",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 87579,
"upload_time": "2025-10-13T20:49:32",
"upload_time_iso_8601": "2025-10-13T20:49:32.989436Z",
"url": "https://files.pythonhosted.org/packages/9b/21/c80aad2a787fdd90e0ea368fa378d0ae80d8162e5d246fd850465eea3565/awslabs_bedrock_kb_retrieval_mcp_server-1.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-13 20:49:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "awslabs",
"github_project": "mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "awslabs.bedrock-kb-retrieval-mcp-server"
}
JSON
