\n\n
![\"Storage](\"./assets/storage_mcp_demo_thumbnail.png\")
\n\n![\"Natural](\"./assets/natural_language.gif\")
\n\n- **Automate and simplify complex workflows.** Chain multiple storage operations\n into a single, repeatable command to reduce manual effort and the chance of\n error.\n\n ![\"Chained](\"./assets/chained.gif\")
\n\n- **Lower the barrier to entry for cloud storage management.** Empower team\n members who are less familiar with GCS to perform powerful actions confidently\n and safely.\n\n ![\"Easy](\"./assets/easy_access_3x.gif\")
\n\n- **Perform analytical and aggregation queries on your objects and buckets.** Perform\n aggregations and compute statistics on entire storage inventory using [Storage Insights\n Datasets](https://cloud.google.com/storage/docs/insights/datasets)\n\n ![\"Easy](\"./assets/storage_insights_aggregation.gif\")
\n\n- **Run advanced filters and searches on your data.** Search and filter your objects\n by file type, size and other metadata fields using [Storage Insights\n Datasets](https://cloud.google.com/storage/docs/insights/datasets)\n\n ![\"Easy](\"./assets/storage_insights_filter.gif\")
\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm):\n version 20 or higher\n- [gcloud CLI](https://cloud.google.com/sdk/docs/install) (for authentication)\n\n## ✨ Set up your MCP server\n\n### Gemini CLI and Gemini Code Assist\n\nTo integrate the Storage MCP server with Gemini CLI or Gemini Code Assist, run the\nsetup command below. This will install the MCP server as a\n[Gemini CLI extension](https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md)\nfor the current user, making it available for all your projects.\n\n```shell\nnpx @google-cloud/storage-mcp init --agent=gemini-cli\n```\n\nAfter the initialization process, you can verify that the storage-mcp server is\nconfigured correctly by running the following command:\n\n```\ngemini mcp list\n\n> ✓ gcs: npx -y @google-cloud/storage-mcp (stdio) - Connected\n```\n\nBy default, the server only enables safe, non-destructive tools. To enable\ntools that can modify or delete existing data, use the\n`--enable-destructive-tools` flag:\n\n```shell\nnpx @google-cloud/storage-mcp init --agent=gemini-cli --enable-destructive-tools\n```\n\n### For other AI clients\n\nTo use the Storage MCP server with other clients, add the following snippet to their\nrespective JSON configuration files:\n\n```json\n\"gcs\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@google-cloud/storage-mcp\"]\n}\n```\n\nInstructions for popular tools:\n\n- **Claude Desktop:** Open **Claude > Settings > Developer > Edit Config** and\n edit `claude_desktop_config.json`.\n- **Cline:** Click the MCP Servers icon, then **Configure MCP Servers** to edit\n `cline_mcp_settings.json`.\n- **Cursor:** Edit `.cursor/mcp.json` for a single project or\n `~/.cursor/mcp.json` for all projects.\n- **Gemini CLI (Manual Setup):**\n [If not using extensions](#gemini-cli-and-gemini-code-assist), edit\n `.gemini/settings.json` for a single project or `~/.gemini/settings.json` for\n all projects.\n\nFor **Visual Studio Code** edit the `.vscode/mcp.json` file in your workspace\nfor a single project or your global user settings file for all projects:\n\n```json\n\"servers\": {\n \"gcs\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@google-cloud/storage-mcp\"]\n }\n}\n```\n\n## 🛠 Local Development\n\nFor more information regarding installing the repository locally, please see\n[development.md](doc/DEVELOPMENT.md)\n\n### Testing\n\nTo run the integration or E2E tests, you will need to set the\n`GOOGLE_CLOUD_PROJECT` or `GCP_PROJECT_ID` environment variable to a valid\nGoogle Cloud project ID.\n\n```shell\nexport GOOGLE_CLOUD_PROJECT=your-gcp-project-id\nnpm run test:integration --workspace=packages/storage-mcp\nnpm run test:e2e --workspace=packages/storage-mcp\n```\n\n## 🧰 Available MCP Tools\n\nThe Storage MCP server offers two sets of tools: **Safe Tools** and\n**Destructive Tools**. By default, only the safe tools are enabled to prevent\naccidental data loss.\n\n### Safe Tools\n\nSafe tools are read-only or only create new objects without affecting existing\nones. They will never modify or delete existing data in GCS.\n\n| Tool | Description |\n| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |\n| `list_buckets` | Lists all buckets in a project. |\n| `get_bucket_metadata` | Gets comprehensive metadata for a specific bucket. |\n| `get_bucket_location` | Gets the location of a bucket. |\n| `view_iam_policy` | Views the IAM policy for a bucket. |\n| `check_iam_permissions` | Tests IAM permissions for a bucket. |\n| `create_bucket` | Creates a new bucket. Fails if the bucket already exists. |\n| `list_objects` | Lists objects in a GCS bucket. |\n| `read_object_metadata` | Reads comprehensive metadata for a specific object. |\n| `read_object_content` | Reads the content of a specific object. |\n| `write_object_new` | Writes a new object. Fails if the object already exists. |\n| `upload_object_new` | Uploads a file to a new object. Fails if the object already exists. |\n| `copy_object_new` | Copies an object to a new destination. Fails if the destination already exists. |\n| `get_metadata_table_schema` | Checks if GCS insights service is enabled and returns the BigQuery table schema for a given insights dataset configuration. |\n| `execute_insights_query` | Executes a BigQuery SQL query against an insights dataset and returns the result. |\n| `list_insights_configs` | Lists the names of all Storage Insights dataset configurations for a given project. |\n\n### Destructive Tools\n\n**Warning:** These tools can permanently modify or delete existing data. Enable\nthem only when you are confident that the agent should be allowed to perform\nthese actions.\n\nYou can enable them by running the `init` command with the\n`--enable-destructive-tools` flag. When enabled, these tools replace their safe\ncounterparts (e.g., `write_object` is registered instead of `write_object_new`).\n\n| Tool | Description |\n| :----------------------- | :--------------------------------------------------------- |\n| `delete_bucket` | **Deletes** a bucket. |\n| `update_bucket_labels` | **Modifies** labels for a bucket. |\n| `delete_object` | **Deletes** a specific object from a bucket. |\n| `update_object_metadata` | **Modifies** the custom metadata of an existing object. |\n| `download_object` | Downloads an object, **overwriting** the destination file. |\n| `move_object` | **Moves** an object (copies then deletes the original). |\n| `write_object` | Writes an object, **overwriting** it if it already exists. |\n| `upload_object` | Uploads a file, **overwriting** the destination object. |\n| `copy_object` | Copies an object, **overwriting** the destination object. |\n\n## 🔑 MCP Permissions\n\nThe permissions of the Storage MCP are directly tied to the permissions of the\nauthenticated user or service account. To restrict permissions and operate with\nthe principle of least privilege, you can\n[authorize gcloud as a service account](https://cloud.google.com/sdk/docs/authorizing#service-account)\nand assign the service account a\n[role with limited permissions](https://cloud.google.com/iam/docs/roles-overview)\nfor Google Cloud Storage.\n\n## 👥 Contributing\n\nWe welcome contributions! Whether you're fixing bugs, sharing feedback, or\nimproving documentation, your contributions are welcome. Please read our\n[Contributing Guide](CONTRIBUTING.md) to get started.\n\n## 🎬 Demos\n\nClick to watch the Storage MCP demo
\n\n\n\n
Click to watch the Storage MCP demo powered by Storage Insights
\n\n![\"Storage](\"./assets/storage_insights_demo_thumbnail.png\")
\n\n