# s3-tools MCP Server

An MCP server that provides tools for interacting with AWS S3 buckets. This server enables direct access to S3 bucket operations through the Model Context Protocol.

## Features

### Tools

The server currently implements the following tools:

- **list-s3-buckets**: Lists all S3 buckets in your AWS account
  - Optional `region` parameter to specify AWS region
  - Returns a formatted list of bucket names

## Prerequisites

- Python 3.13 or higher
- AWS credentials configured (see [AWS Credentials Setup](#aws-credentials-setup))
- [uv](https://github.com/astral-sh/uv) package manager

## Installation

### From PyPI

```bash
uvx install s3-tools
```

### From Source

1. Clone the repository
2. Install using uv:
```bash
uv pip install .
```

## AWS Credentials Setup

This server requires AWS credentials to access your S3 buckets. You can configure credentials in several ways:

1. **AWS CLI configuration** (Recommended)
   ```bash
   aws configure
   ```
   This will create/update credentials in `~/.aws/credentials`

2. **Environment Variables**
   ```bash
   export AWS_ACCESS_KEY_ID="your_access_key"
   export AWS_SECRET_ACCESS_KEY="your_secret_key"
   export AWS_DEFAULT_REGION="your_preferred_region"  # optional
   ```

3. **IAM Role** (if running on AWS infrastructure)

For more information about AWS credentials, see the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).

## Configuration

### Claude Desktop

Add the server configuration to your Claude Desktop config file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "s3-tools": {
      "command": "uvx",
      "args": ["s3-tools"]
    }
  }
}
```

### Development Configuration

For development/testing, you can run the server directly from source:

```json
{
  "mcpServers": {
    "s3-tools": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/s3-tools",
        "run",
        "s3-tools"
      ]
    }
  }
}
```

## Development

### Building

1. Sync dependencies:
```bash
uv sync
```

2. Build package:
```bash
uv build
```

### Publishing

To publish to PyPI:

```bash
uv publish
```

Note: You'll need PyPI credentials configured via:
- Token: `--token` or `UV_PUBLISH_TOKEN`
- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`

### Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for development:

```bash
npx @modelcontextprotocol/inspector uv run s3-tools
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.