{"_id":"@mseep/aws-s3-mcp","name":"@mseep/aws-s3-mcp","dist-tags":{"latest":"0.2.5"},"versions":{"0.2.5":{"name":"@mseep/aws-s3-mcp","version":"0.2.5","description":"MCP Server for S3","repository":{"type":"git","url":"git+https://github.com/samuraikun/aws-s3-mcp.git"},"main":"dist/index.js","bin":{"aws-s3-mcp":"dist/index.js"},"scripts":{"build":"tsc && chmod +x dist/index.js","start":"node dist/index.js","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublish":"npm run build","lint":"npx @biomejs/biome lint .","format":"npx @biomejs/biome format . --write","check:format":"npx @biomejs/biome check .","docker:build":"docker build -t aws-s3-mcp .","docker:run":"docker run --rm --name aws-s3-mcp -p 3000:3000 aws-s3-mcp"},"keywords":["mcp","s3","aws","modelcontextprotocol","mseep","mcp-server"],"author":{"name":"Yuichi Kojima"},"license":"MIT","engines":{"node":">=18"},"dependencies":{"@aws-sdk/client-s3":"^3.758.0","@modelcontextprotocol/sdk":"^1.9.0","dotenv":"^16.4.7","pdf-parse":"^1.1.1","ts-pattern":"^5.6.2","zod-to-json-schema":"^3.24.3"},"devDependencies":{"@biomejs/biome":"1.9.4","@types/node":"^22.13.10","@types/pdf-parse":"^1.1.4","@vitest/coverage-v8":"^3.0.8","aws-sdk-mock":"^6.2.1","typescript":"^5.8.2","vitest":"^3.0.8"},"publisher":"mseep","_id":"@mseep/aws-s3-mcp@0.2.5","gitHead":"287ad7e068f34210e0e4d0cb253ce6d371aa071a","bugs":{"url":"https://github.com/samuraikun/aws-s3-mcp/issues"},"homepage":"https://github.com/samuraikun/aws-s3-mcp#readme","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-kIyTDmLB03czna1kKzKp/B+R2x0/j4Y9NlXDwiDwffTeQHONolsBaaoVz4xQblCkp+sgvmPSwCd40D4RtTYZOQ==","shasum":"b70bf17bfa1db3e35dc3131f47d90139abcf9a34","tarball":"https://registry.npmjs.org/@mseep/aws-s3-mcp/-/aws-s3-mcp-0.2.5.tgz","fileCount":13,"unpackedSize":29082,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHag4A6kNq7kYXwcMleU0v13CUrY7HSRODNwkaV/FwtGAiBlGg9xE1///tuhe8KMxiqpcAYlNFDKjV/a1CfC9progA=="}]},"_npmUser":{"name":"skydeckai","email":"support@skydeck.ai"},"directories":{},"maintainers":[{"name":"skydeckai","email":"support@skydeck.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aws-s3-mcp_0.2.5_1744774075451_0.3949966577717643"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-16T03:27:55.394Z","0.2.5":"2025-04-16T03:27:55.675Z","modified":"2025-04-16T03:27:55.912Z"},"maintainers":[{"name":"skydeckai","email":"support@skydeck.ai"}],"description":"MCP Server for S3","homepage":"https://github.com/samuraikun/aws-s3-mcp#readme","keywords":["mcp","s3","aws","modelcontextprotocol","mseep","mcp-server"],"repository":{"type":"git","url":"git+https://github.com/samuraikun/aws-s3-mcp.git"},"author":{"name":"Yuichi Kojima"},"bugs":{"url":"https://github.com/samuraikun/aws-s3-mcp/issues"},"license":"MIT","readme":"# S3 MCP Server\n\nAn Amazon S3 Model Context Protocol (MCP) server that provides tools for interacting with S3 buckets and objects.\n\nhttps://github.com/user-attachments/assets/d05ff0f1-e2bf-43b9-8d0c-82605abfb666\n\n## Overview\n\nThis MCP server allows Large Language Models (LLMs) like Claude to interact with AWS S3 storage. It provides tools for:\n\n- Listing available S3 buckets\n- Listing objects within a bucket\n- Retrieving object contents\n\nThe server is built using TypeScript and the MCP SDK, providing a secure and standardized way for LLMs to interface with S3.\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18 or higher\n- npm or yarn\n- AWS credentials configured (either through environment variables or AWS credentials file)\n\n### Setup\n\n1. Install via npm:\n\n```bash\n# Install globally via npm\nnpm install -g aws-s3-mcp\n\n# Or as a dependency in your project\nnpm install aws-s3-mcp\n```\n\n2. If building from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/samuraikun/aws-s3-mcp.git\ncd aws-s3-mcp\n\n# Install dependencies and build\nnpm install\nnpm run build\n```\n\n3. Configure AWS credentials and S3 access:\n\nCreate a `.env` file with your AWS configuration:\n\n```\nAWS_REGION=us-east-1\nS3_BUCKETS=bucket1,bucket2,bucket3\nS3_MAX_BUCKETS=5\nAWS_ACCESS_KEY_ID=your-access-key\nAWS_SECRET_ACCESS_KEY=your-secret-key\n```\n\nOr set these as environment variables.\n\n## Configuration\n\nThe server can be configured using the following environment variables:\n\n| Variable                | Description                                       | Default           |\n| ----------------------- | ------------------------------------------------- | ----------------- |\n| `AWS_REGION`            | AWS region where your S3 buckets are located      | `us-east-1`       |\n| `S3_BUCKETS`            | Comma-separated list of allowed S3 bucket names   | (empty)           |\n| `S3_MAX_BUCKETS`        | Maximum number of buckets to return in listing    | `5`               |\n| `AWS_ACCESS_KEY_ID`     | AWS access key (if not using default credentials) | (from AWS config) |\n| `AWS_SECRET_ACCESS_KEY` | AWS secret key (if not using default credentials) | (from AWS config) |\n\n## Running the Server\n\nYou can run the server with Node.js:\n\n```bash\n# Using npx (without installing)\nnpx aws-s3-mcp\n\n# If installed globally\nnpm install -g aws-s3-mcp\naws-s3-mcp\n\n# If running from cloned repository\nnpm start\n\n# Or directly\nnode dist/index.js\n```\n\n## Debugging on MCP Inspector\n\nTo debug the server using MCP Inspector, you can run `sh run-inspector.sh`\n\n```bash\nsh run-inspector.sh\n```\n\n## Connecting to Claude Desktop\n\nTo use this server with Claude Desktop:\n\n1. Edit your Claude Desktop configuration file:\n\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add the S3 MCP server to the configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"s3\": {\n      \"command\": \"npx\",\n      \"args\": [\"aws-s3-mcp\"],\n      \"env\": {\n        \"AWS_REGION\": \"us-east-1\",\n        \"S3_BUCKETS\": \"bucket1,bucket2,bucket3\",\n        \"S3_MAX_BUCKETS\": \"5\",\n        \"AWS_ACCESS_KEY_ID\": \"your-access-key\",\n        \"AWS_SECRET_ACCESS_KEY\": \"your-secret-key\"\n      }\n    }\n  }\n}\n```\n\n> **Important**: Please note the following when using the configuration above\n>\n> - Replace `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` with your actual credentials\n> - `S3_BUCKETS` should contain a comma-separated list of buckets you want to allow access to\n> - `AWS_REGION` should be set to the region where your buckets are located\n\n### 💣 If error occurs on Claude Desktop\n\nIf you encounter errors with the above configuration in Claude Desktop, try using absolute paths as follows:\n\n```bash\n# Get the path of node and aws-s3-mcp\nwhich node\nwhich aws-s3-mcp\n```\n\n```json\n{\n  \"globalShortcut\": \"\",\n  \"mcpServers\": {\n    \"s3\": {\n      \"command\": \"your-absolute-path-to-node\",\n      \"args\": [\"your-absolute-path-to-aws-s3-mcp/dist/index.js\"],\n      \"env\": {\n        \"AWS_REGION\": \"your-aws-region\",\n        \"S3_BUCKETS\": \"your-s3-buckets\",\n        \"S3_MAX_BUCKETS\": \"your-max-buckets\",\n        \"AWS_ACCESS_KEY_ID\": \"your-access-key\",\n        \"AWS_SECRET_ACCESS_KEY\": \"your-secret-key\"\n      }\n    }\n  }\n}\n```\n\n## Available Tools\n\n### list-buckets\n\nLists available S3 buckets that the server has permission to access. This tool respects the `S3_BUCKETS` configuration that limits which buckets are shown.\n\n**Parameters:** None\n\n**Example output:**\n\n```json\n[\n  {\n    \"Name\": \"my-images-bucket\",\n    \"CreationDate\": \"2022-03-15T10:30:00.000Z\"\n  },\n  {\n    \"Name\": \"my-documents-bucket\",\n    \"CreationDate\": \"2023-05-20T14:45:00.000Z\"\n  }\n]\n```\n\n### list-objects\n\nLists objects in a specified S3 bucket.\n\n**Parameters:**\n\n- `bucket` (required): Name of the S3 bucket to list objects from\n- `prefix` (optional): Prefix to filter objects (like a folder path)\n- `maxKeys` (optional): Maximum number of objects to return\n\n**Example output:**\n\n```json\n[\n  {\n    \"Key\": \"sample.pdf\",\n    \"LastModified\": \"2023-10-10T08:12:15.000Z\",\n    \"Size\": 2048576,\n    \"StorageClass\": \"STANDARD\"\n  },\n  {\n    \"Key\": \"sample.md\",\n    \"LastModified\": \"2023-10-12T15:30:45.000Z\",\n    \"Size\": 1536000,\n    \"StorageClass\": \"STANDARD\"\n  }\n]\n```\n\n### get-object\n\nRetrieves an object from a specified S3 bucket. Text files are returned as plain text, while binary files are returned with limited details.\n\n**Parameters:**\n\n- `bucket` (required): Name of the S3 bucket\n- `key` (required): Key (path) of the object to retrieve\n\n**Example text output:**\n\n```\nThis is the content of a text file stored in S3.\nIt could be JSON, TXT, CSV or other text-based formats.\n```\n\n**Example binary output:**\n\n```\nBinary content (image/jpeg): base64 data is /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof...\n```\n\n## Security Considerations\n\n- The server will only access buckets specified in the `S3_BUCKETS` environment variable\n- AWS credentials must have appropriate permissions to the buckets\n- Use the principle of least privilege when configuring AWS permissions\n- For production use, consider using IAM roles with specific S3 permissions\n\n## Usage with Claude\n\nWhen interacting with Claude in the desktop app, you can ask it to perform S3 operations like:\n\n- \"List all my S3 buckets\"\n- \"Summarize PDF files in my-documents-bucket\"\n- \"Get the README.txt file from my-documents-bucket\"\n\nClaude will use the appropriate MCP tool to carry out the request and show you the results.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-ebf99b1535c860bae1ed491cd30da9b8"}