# Pinata Cloud MCP

> Pinata Cloud MCP Server handles IPFS pinning and decentralized storage management. Use your AI agent to pin files, manage metadata for NFTs/JSON objects, and organize assets into named groups without touching a dashboard. It gives you granular control over where and how your web3 content lives on the decentralized network.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** ipfs, decentralized-storage, web3, file-pinning, nft-hosting, metadata-management

## Description

**You're running Web3 stuff. You don't wanna leave your chat window open just to manage IPFS pins or metadata.** This server lets your AI agent handle all that decentralized storage work using natural language. It gives you granular control over where and how your web3 content lives on the decentralized network, letting you act like a full-time Web3 architect right from your prompt.

**Getting Set Up and Checking Credentials**
*   `verify_pinata_auth`: Run this tool to check if your connection credentials are valid; it confirms that your agent can talk to Pinata's system. `list_api_keys`: You can use this to see every active API key tied to your account, which is good for a security review. If you need to lock down an old credential, `revoke_api_key` immediately disables or deactivates a specific API key.

**Pinning and Content Management**
*   `pin_json_to_ipfs`: Pin this tool lets your agent take a JSON metadata file and pin it directly to IPFS, guaranteeing it's permanently available on the network. `list_ipfs_pins`: To see everything you’ve stored, this fetches a complete list of every single file hash currently pinned to the decentralized storage. `update_pin_metadata`: If the display name or tags on an existing pin need changing, this modifies that metadata associated with a specific pin hash using plain language instructions. You can also use your agent to remove old content; `remove_ipfs_pin` unpins and removes a specific file hash from your storage.

**Organizing Your Assets into Groups**
*   `list_pin_groups`: To get an index of everything you've organized, this generates a list of all existing pin groups or collections. `create_pin_group`: This tool lets you establish a new named collection or group for related pinned assets. When you need to know what’s inside a specific category, `get_group_details` retrieves all the information about an existing pin group, including its members and settings. If that whole group is obsolete, `remove_pin_group` deletes the entire pin collection group, pulling out all associated metadata links.

**Monitoring Usage and Cleanup**
*   `get_pinning_stats`: This checks your total data usage against your plan limits so you know exactly how much storage you've consumed. `list_api_keys`: You can also use this tool to view credentials, which is necessary for auditing.

Basically, your AI client handles the whole lifecycle of your web3 content: pinning assets using the IPFS network and getting back that unique CID (Content Identifier), keeping a high-fidelity catalog of all your decentralized data. It manages groups so you don't lose track of collections, updates metadata on the fly, tracks exactly how much storage you’re blowing through, and lets you audit and revoke keys without ever touching a dashboard.

## Tools

### create_pin_group
Creates a new named collection or group for related pinned assets.

### remove_pin_group
Deletes an entire pin collection group, removing all associated metadata links.

### get_pinning_stats
Checks the total data usage against your plan limits for operational monitoring.

### get_group_details
Retrieves all information about an existing pin group, including its members and settings.

### list_pin_groups
Generates an index of all existing pin groups or collections you've created.

### list_api_keys
Displays all active API keys associated with your Pinata account for security review.

### list_ipfs_pins
Fetches a complete list of every file and hash currently pinned to the network.

### pin_json_to_ipfs
Pins a JSON metadata file directly to IPFS, making it permanently available on the network.

### revoke_api_key
Immediately disables or deactivates a specific API key for security reasons.

### verify_pinata_auth
Runs a check to confirm that your connection credentials are valid and active.

### remove_ipfs_pin
Removes or unpins a specific file hash from your decentralized storage.

### update_pin_metadata
Modifies the display name, tags, or metadata associated with an existing pin hash.

## Prompt Examples

**Prompt:** 
```
List my last 5 files pinned to IPFS.
```

**Response:** 
```
I've retrieved your recent pins. You have 5 files including 'Profile_Avatar.png' (CID: Qm...) and 'Project_Metadata.json'. Would you like me to create a group for these?
```

**Prompt:** 
```
Upload and pin my application metadata JSON to IPFS with a custom name for easy retrieval.
```

**Response:** 
```
File pinned to IPFS successfully. CID: bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenrj. Name: "app-metadata-v2.json". Size: 4.2 KB. Gateway URL: gateway.pinata.cloud/ipfs/bafkrei... The content is now permanently available on the IPFS network and accessible through any IPFS gateway. Pin status: Pinned across 3 nodes for redundancy.
```

**Prompt:** 
```
List all my pinned files on IPFS and check which ones are consuming the most storage.
```

**Response:** 
```
You have 47 pinned files using 2.3 GB of your 5 GB plan. Top 5 by size: "nft-collection-images.zip" (890 MB), "video-assets-q2.mp4" (456 MB), "product-catalog.json" (234 MB), "user-avatars-batch.tar" (178 MB), "brand-guidelines.pdf" (89 MB). 12 files were pinned in the last 30 days. 8 files have not been accessed in over 90 days and could be candidates for unpinning.
```

## Capabilities

### Pin IPFS Content
Pin any file or JSON object to the decentralized web and immediately get its unique CID.

### Manage Pin Groups
Create, list, or delete organizational groups to categorize your pinned assets.

### Update Metadata Tags
Modify the names and tags associated with existing pins using natural language instructions.

### Check Storage Usage
Retrieve current account data usage statistics, showing how much storage you've consumed.

### List All Pins
Fetch a list of all currently pinned files and retrieve their associated details.

### Control API Keys
Manage your account credentials by listing, revoking, or checking the status of API keys.

## Use Cases

### Pinning a new NFT collection.
A developer needs to deploy 50 metadata JSON files for an NFT drop. They run the agent and prompt it: 'Pin these 50 files and group them as 'Project X Collection.''. The server uses `pin_json_to_ipfs` repeatedly, then runs `create_pin_group`, giving immediate confirmation of all CIDs.

### Cleaning up old assets.
An engineer needs to free up 2GB of storage used by deprecated project files. They prompt: 'List my pins and tell me which ones haven't been touched in 90 days.' The agent runs `list_ipfs_pins`, identifies the stale hashes, and then executes `remove_ipfs_pin` for each one.

### Restructuring data governance.
A team decides to split their old 'Core Assets' group into two. They first run `list_pin_groups`, confirm the ID of the old group, and then use `remove_pin_group` followed by `create_pin_group` for the new structure.

### Checking credentials before deployment.
A team member just updated their API key. Before committing code, they run `verify_pinata_auth`. The agent confirms the connection is live and active, preventing a full build failure later on.

## Benefits

- You get full visibility into your data footprint. By running `get_pinning_stats`, you see exactly how much storage you've used against your plan limit. No guessing games about resource overhead.
- Metadata control is instant. Instead of navigating a separate dashboard to rename an asset, use `update_pin_metadata` via conversation to change the name or tags on any pinned file.
- Organization becomes simple and scalable. You can create new groups with `create_pin_group` or check existing ones using `list_pin_groups`, keeping your decentralized assets properly categorized.
- Security actions are contained. Need to stop a leaked key? Use `revoke_api_key`. Or, if content is deprecated, simply run `remove_ipfs_pin` to unpin the hash immediately.
- Audit trails simplify cleanup. You can list all pins using `list_ipfs_pins`, which lets you identify and target old or unused assets that need pinning removal via `remove_ipfs_pin`.

## How It Works

The bottom line is: you talk to your AI client like talking to a storage manager, and it handles all the API complexity behind the scenes.

1. First, subscribe to the server and provide your Pinata JWT (JSON Web Token) from your API keys settings.
2. Second, prompt your AI client with a specific command—for instance, 'Pin this metadata file and name it v3.'
3. Third, the agent executes the necessary tool calls, returning confirmation of the CID and any relevant status updates.

## Frequently Asked Questions

**How do I check if my API keys are secure using list_api_keys?**
Run `list_api_keys` to see every key currently active. If you spot an unused or compromised key, use `revoke_api_key` immediately to disable it.

**What is the difference between creating a pin group and pinning files?**
Pinning files (`pin_json_to_ipfs`) actually stores the data. Creating a pin group (`create_pin_group`) just creates an organizational container or index for those pins.

**Can I list all my pinned files using list_ipfs_pins?**
Yes, running `list_ipfs_pins` provides a comprehensive report of every file hash currently on the network. It's your primary tool for auditing content.

**How do I change the name of an existing pin? Use update_pin_metadata.**
You use `update_pin_metadata` and provide the specific hash (CID) you want to change, along with the new desired name or tag.

**How do I check if my connection token is valid using `verify_pinata_auth`?**
It immediately confirms your API credentials and network access. If the tool returns a success status, you're good to go; otherwise, re-check your JWT for typos or expiration.

**What is the process for removing an old file using `remove_ipfs_pin`?**
Running this tool unpins the specified CID or hash from IPFS. This action removes Pinata's active pinning commitment, stopping storage fees for that asset.

**How can I track my current usage limits with `get_pinning_stats`?**
The tool gives a detailed breakdown of your total storage consumption against your plan limit. You'll see exactly how much data you've pinned and which categories are using the most space.

**How do I set up a new organized folder with `create_pin_group`?**
You call the tool and provide a unique name for your collection. This establishes a container in Pinata, letting you logically group related assets without manual management.

**Can my AI automatically find the CID (hash) of a specific pinned file?**
Yes! Use the `list_pins` tool. Provide filters like the pin name, and your agent will respond with the unique IPFS hash (CID) and associated technical metadata in seconds.

**How do I find my Pinata JWT?**
Log in to Pinata, navigate to **API Keys**, click **New Key**, and ensure you select all **Admin** permissions. Copy the long **JWT** string provided at the end.