> ## Documentation Index
> Fetch the complete documentation index at: https://asyncmcp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="uv (Recommended)">
    ```bash theme={null}
    # 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
    ```

    <Tip>
      [uv](https://github.com/astral-sh/uv) is a fast Python package manager that we recommend for asyncmcp development.
    </Tip>
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="poetry">
    ```bash theme={null}
    # Add to project
    poetry add asyncmcp

    # Install with extras
    poetry add asyncmcp[dev]  # Development dependencies
    poetry add asyncmcp[test] # Testing dependencies
    ```
  </Tab>

  <Tab title="pipenv">
    ```bash theme={null}
    # Add to Pipfile
    pipenv install asyncmcp

    # Install with extras
    pipenv install asyncmcp[dev]  # Development dependencies
    pipenv install asyncmcp[test] # Testing dependencies
    ```
  </Tab>
</Tabs>

## Requirements

<Info>
  asyncmcp requires **Python 3.10 or higher**.
</Info>

### 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:

<AccordionGroup>
  <Accordion title="AWS Transports (SQS, SNS+SQS)">
    ```bash theme={null}
    # boto3 is required for AWS transports
    uv add boto3

    # For local development with LocalStack
    uv add localstack
    ```
  </Accordion>

  <Accordion title="Webhook Transport">
    ```bash theme={null}
    # For production webhook servers
    uv add uvicorn  # ASGI server
    uv add gunicorn # Production server
    ```
  </Accordion>

  <Accordion title="Development Tools">
    ```bash theme={null}
    # Install development dependencies
    uv add --dev pytest pytest-asyncio pyright ruff

    # Or install with extras
    uv add asyncmcp[dev]
    ```
  </Accordion>
</AccordionGroup>

## Verify Installation

After installation, verify asyncmcp is properly installed:

<CodeGroup>
  ```python Python theme={null}
  import asyncmcp
  print(f"asyncmcp version: {asyncmcp.__version__}")

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

  ```bash Terminal theme={null}
  # Check version
  python -c "import asyncmcp; print(asyncmcp.__version__)"

  # Run tests
  uv run pytest tests/
  ```
</CodeGroup>

## Development Setup

For contributing to asyncmcp or running examples:

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/bh-rat/asyncmcp.git
    cd asyncmcp
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    # Install with uv (recommended)
    uv sync

    # Or with pip
    pip install -e .[dev,test]
    ```
  </Step>

  <Step title="Install Pre-commit Hooks">
    ```bash theme={null}
    pre-commit install
    ```

    <Note>
      Pre-commit hooks automatically format code and check for linting issues before commits.
    </Note>
  </Step>

  <Step title="Set Up LocalStack">
    ```bash theme={null}
    # Install LocalStack
    uv add localstack

    # Start LocalStack
    localstack start

    # Set up test resources
    uv run examples/setup.py
    ```

    <Check>
      LocalStack should be running on `http://localhost:4566`
    </Check>
  </Step>
</Steps>

## Environment Configuration

### AWS Configuration

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

<Tabs>
  <Tab title="LocalStack (Development)">
    ```bash .env theme={null}
    # LocalStack configuration
    AWS_ENDPOINT_URL=http://localhost:4566
    AWS_REGION=us-east-1
    AWS_ACCESS_KEY_ID=test
    AWS_SECRET_ACCESS_KEY=test
    ```
  </Tab>

  <Tab title="AWS (Production)">
    ```bash .env theme={null}
    # 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
    ```
  </Tab>
</Tabs>

### Python Path Configuration

If running examples directly:

```bash theme={null}
# 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:

<CodeGroup>
  ```dockerfile Dockerfile theme={null}
  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"]
  ```

  ```yaml docker-compose.yml theme={null}
  version: '3.8'

  services:
    localstack:
      image: localstack/localstack
      ports:
        - "4566:4566"
      environment:
        - SERVICES=sqs,sns
        - DEBUG=1
    
    mcp-server:
      build: .
      depends_on:
        - localstack
      environment:
        - AWS_ENDPOINT_URL=http://localstack:4566
        - AWS_ACCESS_KEY_ID=test
        - AWS_SECRET_ACCESS_KEY=test
      command: python server.py
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ImportError: No module named 'asyncmcp'">
    Ensure asyncmcp is installed in your current environment:

    ```bash theme={null}
    pip list | grep asyncmcp
    ```

    If not listed, reinstall:

    ```bash theme={null}
    uv add asyncmcp
    ```
  </Accordion>

  <Accordion title="boto3 not found">
    AWS transports require boto3:

    ```bash theme={null}
    uv add boto3
    ```
  </Accordion>

  <Accordion title="LocalStack connection refused">
    Ensure LocalStack is running:

    ```bash theme={null}
    localstack status
    localstack start  # If not running
    ```
  </Accordion>

  <Accordion title="Python version error">
    asyncmcp requires Python 3.10+. Check your version:

    ```bash theme={null}
    python --version
    ```

    Use pyenv or similar to install a compatible version.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run your first asyncmcp server and client
  </Card>

  <Card title="Core Concepts" icon="book" href="/concepts/overview">
    Understand async transports and how they work
  </Card>

  <Card title="Local Development" icon="laptop" href="/guides/local-development">
    Set up LocalStack for development
  </Card>

  <Card title="Examples" icon="code" href="/examples/basic-examples">
    Browse example implementations
  </Card>
</CardGroup>