Installation

Install asyncmcp and set up your development environment

asyncmcp can be installed using various Python package managers. Choose the one that best fits your workflow.

Package Managers

uv (Recommended)

# Add to current project
uv add asyncmcp

# Install globally
uv tool install asyncmcp

# Install with specific extras
uv add asyncmcp[dev]  # Development dependencies
uv add asyncmcp[test] # Testing dependencies

uv is a fast Python package manager that we recommend for asyncmcp development.

pip

# Basic installation
pip install asyncmcp

# Install with extras
pip install asyncmcp[dev]  # Development dependencies
pip install asyncmcp[test] # Testing dependencies

# Install from source
pip install git+https://github.com/bh-rat/asyncmcp.git

poetry

# Add to project
poetry add asyncmcp

# Install with extras
poetry add asyncmcp[dev]  # Development dependencies
poetry add asyncmcp[test] # Testing dependencies

pipenv

# Add to Pipfile
pipenv install asyncmcp

# Install with extras
pipenv install asyncmcp[dev]  # Development dependencies
pipenv install asyncmcp[test] # Testing dependencies

Requirements

asyncmcp requires Python 3.10 or higher.

Core Dependencies

asyncmcp automatically installs these core dependencies:

• mcp - Model Context Protocol implementation
• anyio - Async runtime support
• httpx - HTTP client for webhook transport
• boto3 - AWS SDK for SQS/SNS transports (optional)
• starlette - ASGI framework for webhook server

Optional Dependencies

Depending on your transport choice, you may need additional packages:

AWS Transports (SQS, SNS+SQS)

# boto3 is required for AWS transports
uv add boto3

# For local development with LocalStack
uv add localstack

Webhook Transport

# For production webhook servers
uv add uvicorn  # ASGI server
uv add gunicorn # Production server

Development Tools

# Install development dependencies
uv add --dev pytest pytest-asyncio pyright ruff

# Or install with extras
uv add asyncmcp[dev]

Verify Installation

After installation, verify asyncmcp is properly installed:

Python

import asyncmcp
print(f"asyncmcp version: {asyncmcp.__version__}")

# Check available transports
from asyncmcp import (
    SqsClientConfig,
    SnsSqsClientConfig, 
    WebhookClientConfig,
    StreamableHTTPWebhookClientConfig
)
print("✅ All transports available")

Development Setup

For contributing to asyncmcp or running examples:

1. Clone the Repository

   git clone https://github.com/bh-rat/asyncmcp.git
   cd asyncmcp
   
2. Install Dependencies

   # Install with uv (recommended)
   uv sync
   
   # Or with pip
   pip install -e .[dev,test]
   
3. Install Pre-commit Hooks

   pre-commit install
   

   Pre-commit hooks automatically format code and check for linting issues before commits.

4. Set Up LocalStack

   # Install LocalStack
   uv add localstack
   
   # Start LocalStack
   localstack start
   
   # Set up test resources
   uv run examples/setup.py
   

   LocalStack should be running on http://localhost:4566

Environment Configuration

AWS Configuration

For AWS-based transports (SQS, SNS+SQS), configure your AWS credentials:

LocalStack (Development)

.env

# LocalStack configuration
AWS_ENDPOINT_URL=http://localhost:4566
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test

AWS (Production)

.env

# AWS configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key

# Optional: Use IAM roles instead
AWS_PROFILE=your_profile

Python Path Configuration

If running examples directly:

# Add src to Python path
export PYTHONPATH="${PYTHONPATH}:./src"

# Or use uv run (automatically handles paths)
uv run examples/website_server.py

Docker Setup

For containerized deployments:

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY pyproject.toml .
RUN pip install uv && uv pip install asyncmcp

# Copy application
COPY . .

# Run server
CMD ["python", "server.py"]

Troubleshooting

ImportError: No module named 'asyncmcp'

Ensure asyncmcp is installed in your current environment:

pip list | grep asyncmcp

If not listed, reinstall:

uv add asyncmcp

boto3 not found

AWS transports require boto3:

uv add boto3

LocalStack connection refused

Ensure LocalStack is running:

localstack status
localstack start  # If not running

Python version error

asyncmcp requires Python 3.10+. Check your version:

python --version

Use pyenv or similar to install a compatible version.

Next Steps

Quickstart

Run your first asyncmcp server and client

Core Concepts

Understand async transports and how they work

Local Development

Set up LocalStack for development

Examples

Browse example implementations