mcp-server-s3 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ofer Shapira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# mcp-server-s3
+
+[![npm version](https://img.shields.io/npm/v/mcp-server-s3.svg)](https://www.npmjs.com/package/mcp-server-s3)
+[![npm downloads](https://img.shields.io/npm/dm/mcp-server-s3.svg)](https://www.npmjs.com/package/mcp-server-s3)
+[![CI](https://github.com/ofershap/mcp-server-s3/actions/workflows/ci.yml/badge.svg)](https://github.com/ofershap/mcp-server-s3/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Manage AWS S3 buckets and objects from your AI assistant. Browse files, upload and download content, and generate presigned URLs.
+
+```bash
+npx mcp-server-s3
+```
+
+> Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP client. Uses your existing AWS credentials (`~/.aws/credentials` or environment variables).
+
+![MCP server for AWS S3 bucket management and file operations](assets/demo.gif)
+
+<sub>Demo built with <a href="https://github.com/ofershap/remotion-readme-kit">remotion-readme-kit</a></sub>
+
+## Why
+
+S3 is the most widely used cloud storage service, but managing it from the command line means remembering `aws s3 ls`, `aws s3 cp`, presigned URL syntax, and various flags. Google has an official MCP for GCS, Cloudflare has one for R2, but AWS S3 doesn't have a polished standalone MCP server on npm. This one lets you ask your assistant to list buckets, download a config file, upload content, or generate a temporary sharing link. It uses the standard AWS credential chain, so if your CLI already works, this works too.
+
+## Tools
+
+| Tool            | What it does                                           |
+| --------------- | ------------------------------------------------------ |
+| `list_buckets`  | List all S3 buckets in your AWS account.               |
+| `list_objects`  | List objects in a bucket, with optional prefix filter. |
+| `get_object`    | Download and read an object's content as text.         |
+| `put_object`    | Upload text content to an S3 object.                   |
+| `delete_object` | Delete an object from a bucket.                        |
+| `presigned_url` | Generate a temporary presigned URL for an object.      |
+| `bucket_info`   | Check if a bucket exists and get basic info.           |
+
+## Quick Start
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "s3": {
+      "command": "npx",
+      "args": ["mcp-server-s3"],
+      "env": {
+        "AWS_REGION": "us-east-1",
+        "AWS_ACCESS_KEY_ID": "your-access-key",
+        "AWS_SECRET_ACCESS_KEY": "your-secret-key"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "s3": {
+      "command": "npx",
+      "args": ["mcp-server-s3"],
+      "env": {
+        "AWS_REGION": "us-east-1",
+        "AWS_ACCESS_KEY_ID": "your-access-key",
+        "AWS_SECRET_ACCESS_KEY": "your-secret-key"
+      }
+    }
+  }
+}
+```
+
+### VS Code
+
+Configure the MCP server to run `npx mcp-server-s3` with `AWS_REGION`, `AWS_ACCESS_KEY_ID`, and `AWS_SECRET_ACCESS_KEY` in the environment.
+
+## Authentication
+
+The server uses the standard AWS credential chain:
+
+1. **Environment variables**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
+2. **Shared credentials file**: `~/.aws/credentials`
+3. **IAM roles**: when running on EC2, ECS, Lambda, or similar
+
+Set `AWS_REGION` (defaults to `us-east-1`) and make sure your credentials have the necessary S3 permissions: `s3:ListBuckets`, `s3:ListBucket`, `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, `s3:HeadBucket`.
+
+## Example prompts
+
+- "List all my S3 buckets"
+- "Show me the files in my-bucket/uploads/"
+- "Download the config.json from my-bucket"
+- "Upload this content to my-bucket/notes.txt"
+- "Generate a presigned URL for this file that expires in 1 hour"
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+npm run format
+npm run lint
+```
+
+## Author
+
+**Ofer Shapira**
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-ofershap-blue?logo=linkedin)](https://linkedin.com/in/ofershap)
+[![GitHub](https://img.shields.io/badge/GitHub-ofershap-black?logo=github)](https://github.com/ofershap)
+
+## License
+
+MIT © 2026 Ofer Shapira

package/dist/index.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/s3.ts
+import {
+  S3Client,
+  ListBucketsCommand,
+  ListObjectsV2Command,
+  GetObjectCommand,
+  PutObjectCommand,
+  DeleteObjectCommand,
+  HeadBucketCommand
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+var defaultRegion = process.env.AWS_REGION ?? "us-east-1";
+function createClient() {
+  return new S3Client({ region: defaultRegion });
+}
+async function listBuckets() {
+  const client = createClient();
+  const result = await client.send(new ListBucketsCommand({}));
+  const buckets = result.Buckets ?? [];
+  return buckets.map((b) => ({
+    name: b.Name ?? "",
+    creationDate: b.CreationDate
+  }));
+}
+async function listObjects(bucket, prefix, maxKeys = 100) {
+  const client = createClient();
+  const result = await client.send(
+    new ListObjectsV2Command({
+      Bucket: bucket,
+      Prefix: prefix,
+      MaxKeys: maxKeys,
+      Delimiter: "/"
+    })
+  );
+  const items = [];
+  for (const cp of result.CommonPrefixes ?? []) {
+    if (cp.Prefix) {
+      items.push({ key: cp.Prefix, isPrefix: true });
+    }
+  }
+  for (const obj of result.Contents ?? []) {
+    if (obj.Key) {
+      items.push({
+        key: obj.Key,
+        size: obj.Size,
+        lastModified: obj.LastModified,
+        isPrefix: false
+      });
+    }
+  }
+  return items;
+}
+async function getObject(bucket, key) {
+  const client = createClient();
+  const result = await client.send(
+    new GetObjectCommand({ Bucket: bucket, Key: key })
+  );
+  const body = result.Body;
+  if (!body) {
+    throw new Error(`Object ${key} has no body`);
+  }
+  const chunks = [];
+  for await (const chunk of body) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function putObject(bucket, key, content, contentType) {
+  const client = createClient();
+  await client.send(
+    new PutObjectCommand({
+      Bucket: bucket,
+      Key: key,
+      Body: Buffer.from(content, "utf-8"),
+      ContentType: contentType ?? "text/plain"
+    })
+  );
+}
+async function deleteObject(bucket, key) {
+  const client = createClient();
+  await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+}
+async function presignedUrl(bucket, key, expiresIn = 3600) {
+  const client = createClient();
+  const command = new GetObjectCommand({ Bucket: bucket, Key: key });
+  return getSignedUrl(client, command, { expiresIn });
+}
+async function bucketInfo(bucket) {
+  const client = createClient();
+  try {
+    await client.send(new HeadBucketCommand({ Bucket: bucket }));
+    return {
+      name: bucket,
+      exists: true,
+      region: defaultRegion
+    };
+  } catch {
+    return { name: bucket, exists: false };
+  }
+}
+
+// src/index.ts
+function formatBuckets(buckets) {
+  if (buckets.length === 0) return "No buckets found.";
+  return buckets.map(
+    (b) => `  \u2022 ${b.name}${b.creationDate ? ` (created: ${b.creationDate.toISOString()})` : ""}`
+  ).join("\n");
+}
+function formatObjects(items) {
+  if (items.length === 0) return "No objects found.";
+  return items.map((o) => {
+    if (o.isPrefix) return `  \u{1F4C1} ${o.key}`;
+    const size = o.size != null ? ` (${o.size} B)` : "";
+    const modified = o.lastModified != null ? ` \u2014 ${o.lastModified.toISOString()}` : "";
+    return `  \u{1F4C4} ${o.key}${size}${modified}`;
+  }).join("\n");
+}
+var server = new McpServer({
+  name: "mcp-server-s3",
+  version: "1.0.0"
+});
+server.tool(
+  "list_buckets",
+  "List all S3 buckets in your AWS account.",
+  {},
+  async () => {
+    try {
+      const buckets = await listBuckets();
+      const text = `Buckets (${buckets.length}):
+
+${formatBuckets(buckets)}`;
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "list_objects",
+  "List objects in an S3 bucket. Optionally filter by prefix and limit count.",
+  {
+    bucket: z.string().describe("Bucket name"),
+    prefix: z.string().optional().describe("Key prefix (e.g. 'uploads/')"),
+    maxKeys: z.number().int().min(1).max(1e3).default(100).describe("Max objects to return")
+  },
+  async ({ bucket, prefix, maxKeys }) => {
+    try {
+      const items = await listObjects(bucket, prefix, maxKeys);
+      const header = prefix ? `Objects in s3://${bucket}/${prefix} (max ${maxKeys}):
+
+` : `Objects in s3://${bucket}/ (max ${maxKeys}):
+
+`;
+      const text = header + formatObjects(items);
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "get_object",
+  "Download and read the contents of an S3 object as text.",
+  {
+    bucket: z.string().describe("Bucket name"),
+    key: z.string().describe("Object key")
+  },
+  async ({ bucket, key }) => {
+    try {
+      const content = await getObject(bucket, key);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Content of s3://${bucket}/${key}:
+
+${content}`
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "put_object",
+  "Upload text content to an S3 object.",
+  {
+    bucket: z.string().describe("Bucket name"),
+    key: z.string().describe("Object key"),
+    content: z.string().describe("Content to upload"),
+    contentType: z.string().optional().describe("Content-Type header (default: text/plain)")
+  },
+  async ({ bucket, key, content, contentType }) => {
+    try {
+      await putObject(bucket, key, content, contentType);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `\u2705 Uploaded ${content.length} bytes to s3://${bucket}/${key}`
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "delete_object",
+  "Delete an object from an S3 bucket.",
+  {
+    bucket: z.string().describe("Bucket name"),
+    key: z.string().describe("Object key")
+  },
+  async ({ bucket, key }) => {
+    try {
+      await deleteObject(bucket, key);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `\u2705 Deleted s3://${bucket}/${key}`
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "presigned_url",
+  "Generate a presigned URL for temporary access to an S3 object.",
+  {
+    bucket: z.string().describe("Bucket name"),
+    key: z.string().describe("Object key"),
+    expiresIn: z.number().int().min(60).max(604800).default(3600).describe("URL expiry in seconds (default: 1 hour)")
+  },
+  async ({ bucket, key, expiresIn }) => {
+    try {
+      const url = await presignedUrl(bucket, key, expiresIn);
+      const hrs = Math.round(expiresIn / 3600);
+      const text = `Presigned URL for s3://${bucket}/${key} (valid ~${hrs}h):
+
+${url}`;
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "bucket_info",
+  "Check if a bucket exists and get basic info.",
+  {
+    bucket: z.string().describe("Bucket name")
+  },
+  async ({ bucket }) => {
+    try {
+      const info = await bucketInfo(bucket);
+      const status = info.exists ? "\u2705 Exists" : "\u274C Not found / no access";
+      const region = info.region ? `
+Region: ${info.region}` : "";
+      const text = `Bucket: ${bucket}
+${status}${region}`;
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/s3.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { z } from \"zod\";\nimport {\n  listBuckets,\n  listObjects,\n  getObject,\n  putObject,\n  deleteObject,\n  presignedUrl,\n  bucketInfo,\n  type ObjectInfo,\n} from \"./s3.js\";\n\nfunction formatBuckets(\n  buckets: { name: string; creationDate?: Date }[],\n): string {\n  if (buckets.length === 0) return \"No buckets found.\";\n  return buckets\n    .map(\n      (b) =>\n        `  • ${b.name}${b.creationDate ? ` (created: ${b.creationDate.toISOString()})` : \"\"}`,\n    )\n    .join(\"\\n\");\n}\n\nfunction formatObjects(items: ObjectInfo[]): string {\n  if (items.length === 0) return \"No objects found.\";\n  return items\n    .map((o) => {\n      if (o.isPrefix) return `  📁 ${o.key}`;\n      const size = o.size != null ? ` (${o.size} B)` : \"\";\n      const modified =\n        o.lastModified != null ? ` — ${o.lastModified.toISOString()}` : \"\";\n      return `  📄 ${o.key}${size}${modified}`;\n    })\n    .join(\"\\n\");\n}\n\nconst server = new McpServer({\n  name: \"mcp-server-s3\",\n  version: \"1.0.0\",\n});\n\nserver.tool(\n  \"list_buckets\",\n  \"List all S3 buckets in your AWS account.\",\n  {},\n  async () => {\n    try {\n      const buckets = await listBuckets();\n      const text = `Buckets (${buckets.length}):\\n\\n${formatBuckets(buckets)}`;\n      return { content: [{ type: \"text\", text }] };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"list_objects\",\n  \"List objects in an S3 bucket. Optionally filter by prefix and limit count.\",\n  {\n    bucket: z.string().describe(\"Bucket name\"),\n    prefix: z.string().optional().describe(\"Key prefix (e.g. 'uploads/')\"),\n    maxKeys: z\n      .number()\n      .int()\n      .min(1)\n      .max(1000)\n      .default(100)\n      .describe(\"Max objects to return\"),\n  },\n  async ({ bucket, prefix, maxKeys }) => {\n    try {\n      const items = await listObjects(bucket, prefix, maxKeys);\n      const header = prefix\n        ? `Objects in s3://${bucket}/${prefix} (max ${maxKeys}):\\n\\n`\n        : `Objects in s3://${bucket}/ (max ${maxKeys}):\\n\\n`;\n      const text = header + formatObjects(items);\n      return { content: [{ type: \"text\", text }] };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"get_object\",\n  \"Download and read the contents of an S3 object as text.\",\n  {\n    bucket: z.string().describe(\"Bucket name\"),\n    key: z.string().describe(\"Object key\"),\n  },\n  async ({ bucket, key }) => {\n    try {\n      const content = await getObject(bucket, key);\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Content of s3://${bucket}/${key}:\\n\\n${content}`,\n          },\n        ],\n      };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"put_object\",\n  \"Upload text content to an S3 object.\",\n  {\n    bucket: z.string().describe(\"Bucket name\"),\n    key: z.string().describe(\"Object key\"),\n    content: z.string().describe(\"Content to upload\"),\n    contentType: z\n      .string()\n      .optional()\n      .describe(\"Content-Type header (default: text/plain)\"),\n  },\n  async ({ bucket, key, content, contentType }) => {\n    try {\n      await putObject(bucket, key, content, contentType);\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `✅ Uploaded ${content.length} bytes to s3://${bucket}/${key}`,\n          },\n        ],\n      };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"delete_object\",\n  \"Delete an object from an S3 bucket.\",\n  {\n    bucket: z.string().describe(\"Bucket name\"),\n    key: z.string().describe(\"Object key\"),\n  },\n  async ({ bucket, key }) => {\n    try {\n      await deleteObject(bucket, key);\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `✅ Deleted s3://${bucket}/${key}`,\n          },\n        ],\n      };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"presigned_url\",\n  \"Generate a presigned URL for temporary access to an S3 object.\",\n  {\n    bucket: z.string().describe(\"Bucket name\"),\n    key: z.string().describe(\"Object key\"),\n    expiresIn: z\n      .number()\n      .int()\n      .min(60)\n      .max(604800)\n      .default(3600)\n      .describe(\"URL expiry in seconds (default: 1 hour)\"),\n  },\n  async ({ bucket, key, expiresIn }) => {\n    try {\n      const url = await presignedUrl(bucket, key, expiresIn);\n      const hrs = Math.round(expiresIn / 3600);\n      const text = `Presigned URL for s3://${bucket}/${key} (valid ~${hrs}h):\\n\\n${url}`;\n      return { content: [{ type: \"text\", text }] };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"bucket_info\",\n  \"Check if a bucket exists and get basic info.\",\n  {\n    bucket: z.string().describe(\"Bucket name\"),\n  },\n  async ({ bucket }) => {\n    try {\n      const info = await bucketInfo(bucket);\n      const status = info.exists ? \"✅ Exists\" : \"❌ Not found / no access\";\n      const region = info.region ? `\\nRegion: ${info.region}` : \"\";\n      const text = `Bucket: ${bucket}\\n${status}${region}`;\n      return { content: [{ type: \"text\", text }] };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nasync function main() {\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n}\n\nmain().catch((err) => {\n  console.error(\"Fatal error:\", err);\n  process.exit(1);\n});\n","import {\n  S3Client,\n  ListBucketsCommand,\n  ListObjectsV2Command,\n  GetObjectCommand,\n  PutObjectCommand,\n  DeleteObjectCommand,\n  HeadBucketCommand,\n} from \"@aws-sdk/client-s3\";\nimport { getSignedUrl } from \"@aws-sdk/s3-request-presigner\";\n\nconst defaultRegion = process.env.AWS_REGION ?? \"us-east-1\";\n\nfunction createClient(): S3Client {\n  return new S3Client({ region: defaultRegion });\n}\n\nexport interface BucketInfo {\n  name: string;\n  creationDate?: Date;\n}\n\nexport interface ObjectInfo {\n  key: string;\n  size?: number;\n  lastModified?: Date;\n  isPrefix?: boolean;\n}\n\nexport interface BucketDetails {\n  name: string;\n  exists: boolean;\n  region?: string;\n}\n\nexport async function listBuckets(): Promise<BucketInfo[]> {\n  const client = createClient();\n  const result = await client.send(new ListBucketsCommand({}));\n  const buckets = result.Buckets ?? [];\n  return buckets.map((b) => ({\n    name: b.Name ?? \"\",\n    creationDate: b.CreationDate,\n  }));\n}\n\nexport async function listObjects(\n  bucket: string,\n  prefix?: string,\n  maxKeys = 100,\n): Promise<ObjectInfo[]> {\n  const client = createClient();\n  const result = await client.send(\n    new ListObjectsV2Command({\n      Bucket: bucket,\n      Prefix: prefix,\n      MaxKeys: maxKeys,\n      Delimiter: \"/\",\n    }),\n  );\n  const items: ObjectInfo[] = [];\n\n  for (const cp of result.CommonPrefixes ?? []) {\n    if (cp.Prefix) {\n      items.push({ key: cp.Prefix, isPrefix: true });\n    }\n  }\n  for (const obj of result.Contents ?? []) {\n    if (obj.Key) {\n      items.push({\n        key: obj.Key,\n        size: obj.Size,\n        lastModified: obj.LastModified,\n        isPrefix: false,\n      });\n    }\n  }\n  return items;\n}\n\nexport async function getObject(bucket: string, key: string): Promise<string> {\n  const client = createClient();\n  const result = await client.send(\n    new GetObjectCommand({ Bucket: bucket, Key: key }),\n  );\n  const body = result.Body;\n  if (!body) {\n    throw new Error(`Object ${key} has no body`);\n  }\n  const chunks: Uint8Array[] = [];\n  for await (const chunk of body as AsyncIterable<Uint8Array>) {\n    chunks.push(chunk);\n  }\n  return Buffer.concat(chunks).toString(\"utf-8\");\n}\n\nexport async function putObject(\n  bucket: string,\n  key: string,\n  content: string,\n  contentType?: string,\n): Promise<void> {\n  const client = createClient();\n  await client.send(\n    new PutObjectCommand({\n      Bucket: bucket,\n      Key: key,\n      Body: Buffer.from(content, \"utf-8\"),\n      ContentType: contentType ?? \"text/plain\",\n    }),\n  );\n}\n\nexport async function deleteObject(bucket: string, key: string): Promise<void> {\n  const client = createClient();\n  await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));\n}\n\nexport async function presignedUrl(\n  bucket: string,\n  key: string,\n  expiresIn = 3600,\n): Promise<string> {\n  const client = createClient();\n  const command = new GetObjectCommand({ Bucket: bucket, Key: key });\n  return getSignedUrl(client, command, { expiresIn });\n}\n\nexport async function bucketInfo(bucket: string): Promise<BucketDetails> {\n  const client = createClient();\n  try {\n    await client.send(new HeadBucketCommand({ Bucket: bucket }));\n    return {\n      name: bucket,\n      exists: true,\n      region: defaultRegion,\n    };\n  } catch {\n    return { name: bucket, exists: false };\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "mcp-server-s3",
+  "version": "1.0.0",
+  "description": "MCP server for AWS S3 — list buckets, browse objects, upload/download files, and generate presigned URLs from your IDE",
+  "type": "module",
+  "bin": {
+    "mcp-server-s3": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "aws",
+    "s3",
+    "storage",
+    "cloud",
+    "files",
+    "bucket",
+    "presigned-url",
+    "ai",
+    "llm",
+    "claude",
+    "cursor"
+  ],
+  "author": "Ofer Shapira",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ofershap/mcp-server-s3.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ofershap/mcp-server-s3/issues"
+  },
+  "homepage": "https://github.com/ofershap/mcp-server-s3#readme",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^15.0.0",
+    "prettier": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.2.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js}": "eslint --fix",
+    "*.{json,md,yml,yaml}": "prettier --write"
+  }
+}