Bedrock Claude MCP Server

A comprehensive AWS Bedrock MCP (Model Context Protocol) server that provides model listing capabilities and web search tools. This server can be deployed as a serverless Lambda function or run locally for development and testing.

Features

🤖 Bedrock Integration

• List Foundation Models: Browse all available AWS Bedrock models with filtering options
• Model Details: Get detailed information about specific models
• Provider Filtering: Filter models by provider (Anthropic, Amazon, AI21, Cohere, Meta, Mistral)
• Modality Filtering: Filter by input/output modalities (TEXT, IMAGE, EMBEDDING)
• Region Support: Works across all Bedrock-supported AWS regions

🔍 Web Search

• DuckDuckGo Search: Privacy-focused web search capabilities
• Structured Results: Returns formatted search results with titles, URLs, and snippets
• Rate Limiting: Built-in protection against abuse

🚀 Deployment Options

• Local Development: Run locally with stdio, FastAPI, or streamable HTTP
• AWS Lambda: Serverless deployment with Mangum adapter
• API Gateway: Optional API Gateway integration for advanced routing
• Lambda Function URLs: Direct HTTPS access to your MCP server

🛠 MCP Protocol Support

• Tools: Execute functions for model listing and web search
• Resources: Access model information as structured resources
• Prompts: Get guidance on model selection for specific use cases
• Context: Rich logging and progress reporting

Quick Start

Prerequisites

• Python 3.10 or higher
• UV for dependency management
• AWS credentials configured (for Bedrock access)
• Terraform (for AWS deployment)

Local Installation

1. Clone and setup the project:

git clone <repository-url>
cd bedrock_claude_mcp
uv sync

2. Configure AWS credentials:

aws configure
# or set environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1

3. Run locally:

# For MCP client testing (stdio mode)
uv run python -m bedrock_claude_mcp.server --mode stdio

# For web interface testing (FastAPI mode)
uv run python -m bedrock_claude_mcp.server --mode fastapi --host 127.0.0.1 --port 8000

# For MCP over HTTP testing
uv run python -m bedrock_claude_mcp.server --mode streamable-http --host 127.0.0.1 --port 8000

Local MCP Testing (Recommended)

For easy local testing with Claude Desktop, use the automated setup script:

# Test the MCP server functionality
./scripts/test_local_mcp.py

# Setup Claude Desktop configuration automatically
./scripts/setup_local_mcp.sh

The setup script will:

1. ✅ Check prerequisites (uv, AWS credentials, Claude Desktop)
2. 🔧 Create the proper Claude Desktop configuration
3. 📁 Backup any existing configuration
4. 🧪 Test the MCP server startup
5. 📋 Provide next steps for testing

Manual Configuration: If you prefer manual setup, create or update ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bedrock-claude-mcp-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/bedrock_claude_mcp",
        "python",
        "-m",
        "bedrock_claude_mcp.server",
        "--mode",
        "stdio"
      ],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Testing Steps:

1. Run the setup script: ./scripts/setup_local_mcp.sh
2. Restart Claude Desktop
3. In Claude Desktop, you should see the MCP server connected
4. Test with commands like: "List available Bedrock models" or "Search for Python tutorials"

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bedrock-claude-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/bedrock_claude_mcp",
        "python",
        "-m",
        "bedrock_claude_mcp.server",
        "--mode",
        "stdio"
      ]
    }
  }
}

Docker Deployment

Prerequisites for Docker

• Docker and Docker Compose installed
• AWS credentials configured

Quick Docker Start

1. Clone and setup:

git clone <repository-url>
cd bedrock_claude_mcp

2. Configure environment:

# Copy environment template
cp env.example .env

# Edit .env with your AWS credentials
# Required: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION

3. Build and run:

# Build the Docker image
./docker-run.sh build

# Run FastAPI web interface (recommended for testing)
./docker-run.sh fastapi up

# Or run MCP over HTTP
./docker-run.sh http up

# Or test STDIO mode
./docker-run.sh stdio

Docker Usage Examples

# Start FastAPI mode (web interface at http://localhost:8000)
./docker-run.sh fastapi up

# Start MCP HTTP mode (MCP server at http://localhost:8001)
./docker-run.sh http up

# View logs
./docker-run.sh fastapi logs
./docker-run.sh http logs

# Stop services
./docker-run.sh down

# Open shell in container for debugging
./docker-run.sh shell

# Test STDIO mode interactively
./docker-run.sh stdio

Manual Docker Commands

If you prefer manual Docker commands:

# Build image
docker-compose build

# Run FastAPI mode
docker-compose --profile fastapi up -d

# Run MCP HTTP mode  
docker-compose --profile http up -d

# Run STDIO mode (interactive)
docker-compose --profile stdio run --rm bedrock-mcp-stdio

# Stop all services
docker-compose down

Testing the Docker Deployment

1. FastAPI Mode (http://localhost:8000):

   • Visit http://localhost:8000/docs for interactive API documentation
   • Test endpoints directly through the Swagger UI

2. MCP HTTP Mode (http://localhost:8001):

   • Use MCP clients to connect to http://localhost:8001
   • Test with curl or other HTTP clients

3. STDIO Mode:

   • Interactive testing for MCP protocol compliance
   • Useful for debugging and development

AWS Deployment

Using Terraform

1. Navigate to terraform directory:

cd terraform

2. Initialize Terraform:

terraform init

3. Plan deployment:

terraform plan

4. Deploy:

terraform apply

5. Get deployment outputs:

terraform output

Configuration Variables

Create a terraform.tfvars file:

aws_region = "us-east-1"
environment = "prod"
project_name = "bedrock-claude-mcp"
lambda_timeout = 30
lambda_memory_size = 512
log_retention_days = 14
enable_auth = false
create_api_gateway = false

Remote MCP Configuration

After deployment, use the Lambda Function URL for remote access:

{
  "mcpServers": {
    "bedrock-claude-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-function-url.lambda-url.us-east-1.on.aws/mcp/"
      ]
    }
  }
}

Available Tools

Model Management Tools

list_bedrock_models

Lists all available AWS Bedrock models with their capabilities and status.

Example usage:

{
  "name": "list_bedrock_models",
  "arguments": {}
}

Response:

• List of models with details including model ID, name, provider, modalities, and lifecycle information

list_models_by_provider

Lists models filtered by a specific provider (e.g., "Anthropic", "Amazon", "Cohere").

Example usage:

{
  "name": "list_models_by_provider",
  "arguments": {
    "provider": "Anthropic"
  }
}

Web Search Tools

search_web

Search the web using DuckDuckGo with reliable results powered by LangChain's integration.

Example usage:

{
  "name": "search_web",
  "arguments": {
    "query": "MCP protocol Anthropic",
    "max_results": 5
  }
}

Parameters:

• query (string): Search query
• max_results (integer, optional): Maximum number of results to return (default: 10, max: 20)

Response:

• Search results with titles, URLs, snippets, and search metadata
• Results include relevance-ranked web pages
• Fast response times with proper error handling

search_news

Search for recent news articles using DuckDuckGo's news search.

Example usage:

{
  "name": "search_news",
  "arguments": {
    "query": "AI technology updates",
    "max_results": 3
  }
}

Parameters:

• query (string): News search query
• max_results (integer, optional): Maximum number of news articles to return (default: 10)

Response:

• Recent news articles with titles, URLs, snippets, and publication dates
• Filtered for recent content (past day by default)
• Includes metadata like publication timestamps

Regional Information Tools

get_bedrock_regions

Get list of AWS regions where Bedrock is available.

Example usage:

{
  "name": "get_bedrock_regions",
  "arguments": {}
}

Web Search Features

The web search functionality is powered by LangChain's DuckDuckGo integration, providing:

• Reliable Results: Uses the well-tested LangChain community package
• Bot Detection Avoidance: Handles DuckDuckGo's anti-bot measures automatically
• Multiple Search Types: Support for both web and news search
• Structured Output: Consistent result format with title, URL, snippet, and metadata
• Error Handling: Graceful handling of network issues and rate limiting
• Configurable: Adjustable result limits, regions, and safety settings

Search Result Format

Both web and news search return results in this format:

{
  "query": "search query",
  "total_results": 5,
  "search_time_ms": 850.2,
  "results": [
    {
      "title": "Page Title",
      "url": "https://example.com/page",
      "snippet": "Brief description of the content...",
      "published_date": "2025-05-30T10:00:00Z"
    }
  ]
}

Note: published_date is available for news results and may be null for web results.

Available Resources

bedrock://models/{provider}

Access model information for a specific provider as a resource.

Example:

bedrock://models/Anthropic

Available Prompts

model_selection_guide

Get guidance on selecting the right Bedrock model for your use case.

Parameters:

• use_case (required): Description of your intended use case

Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Run specific test file
uv run pytest tests/test_bedrock_client.py

Code Quality

# Format code
uv run ruff format

# Lint code
uv run ruff check

# Type checking
uv run mypy src

Project Structure

bedrock_claude_mcp/
├── src/bedrock_claude_mcp/
│   ├── __init__.py
│   ├── server.py              # Main MCP server implementation
│   ├── bedrock_client.py      # AWS Bedrock client
│   ├── web_search.py          # Web search functionality
│   └── models.py              # Pydantic data models
├── tests/
│   ├── __init__.py
│   └── test_bedrock_client.py # Unit tests
├── terraform/
│   ├── main.tf                # Main Terraform configuration
│   ├── variables.tf           # Terraform variables
│   └── outputs.tf             # Terraform outputs
├── pyproject.toml             # Project configuration
└── README.md                  # This file

Architecture

Local Development

Claude Desktop ←→ MCP Server (stdio) ←→ AWS Bedrock
                                    ←→ DuckDuckGo

AWS Deployment

Claude Desktop ←→ Lambda Function URL ←→ Lambda (FastMCP + Mangum) ←→ AWS Bedrock
                                                                   ←→ DuckDuckGo

Optional API Gateway

Claude Desktop ←→ API Gateway ←→ Lambda (FastMCP + Mangum) ←→ AWS Bedrock
                                                           ←→ DuckDuckGo

Security Considerations

• AWS IAM: Lambda function has minimal required permissions for Bedrock access
• CORS: Properly configured for web access
• Rate Limiting: Built-in protection for web search functionality
• Input Validation: All inputs validated using Pydantic models
• Error Handling: Comprehensive error handling with proper logging

Troubleshooting

Common Issues

1. AWS Credentials: Ensure AWS credentials are properly configured
2. Bedrock Access: Verify your AWS account has access to Bedrock in the target region
3. Model Access: Some Bedrock models require explicit access requests
4. Cold Starts: Lambda cold starts may take 3-5 seconds initially

Debugging

Enable debug logging:

export LOG_LEVEL=DEBUG
uv run python -m bedrock_claude_mcp.server --mode stdio

Check CloudWatch logs for Lambda deployment:

aws logs tail /aws/lambda/bedrock-claude-mcp-dev --follow

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• FastMCP for the excellent MCP framework
• AWS Bedrock for foundation model access
• Model Context Protocol for the standardized protocol