Skip to main content
This page documents all tools available in the Pinata MCP server. Each tool includes its parameters and example prompts you can use with Claude.

​
Authentication

​
testAuthentication

Verify that your Pinata JWT is valid and working. Parameters: None Example Prompt: 
Test my Pinata authentication to make sure everything is working

​
File Operations

​
uploadFile

Upload a file to Pinata IPFS. Provide either a file path or base64-encoded content.
ParameterTypeRequiredDescription
resourceUristringNoFile URI to upload (e.g., file:///path/to/file.jpg)
fileContentstringNoBase64-encoded file content (alternative to resourceUri)
fileNamestringNoName for the uploaded file (auto-detected from path if using resourceUri)
mimeTypestringNoMIME type (auto-detected if not provided)
network"public" | "private"NoUpload to public or private IPFS (default: "public")
group_idstringNoID of a group to add the file to
keyvaluesobjectNoMetadata key-value pairs
Example Prompts: 
Upload the file at ~/Documents/report.pdf to Pinata as a private file

Upload this image to my Pinata account as a public file named "My Logo"

Upload ~/data/config.json to Pinata and add it to group abc123

​
searchFiles

Search for files in your Pinata account by name, CID, or MIME type.
ParameterTypeRequiredDescription
network"public" | "private"NoSearch in public or private IPFS (default: "public")
namestringNoFilter by filename
cidstringNoFilter by content ID (CID)
mimeTypestringNoFilter by MIME type
limitnumberNoMaximum number of results
pageTokenstringNoToken for pagination
Example Prompts: 
Search my Pinata account for all PNG files

Find all files named "report" in my private storage

List my JSON files on Pinata

​
getFileById

Retrieve detailed information about a specific file by its ID.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
idstringYesThe unique ID of the file
Example Prompt: 
Get details for file ID abc123 from my Pinata account

​
updateFile

Update metadata for an existing file including name and key-value pairs.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
idstringYesThe unique ID of the file
namestringNoNew name for the file
keyvaluesobjectNoMetadata key-value pairs to update
Example Prompt: 
Rename file abc123 to "Final Report" and add metadata tag "status": "approved"

​
deleteFile

Delete a file from your Pinata account.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
idstringYesThe unique ID of the file
Example Prompt: 
Delete file abc123 from my Pinata account

​
Content Access

Create a direct access link for a file. For public files returns a gateway URL, for private files generates a temporary download link.
ParameterTypeRequiredDescription
cidstringYesThe CID of the file
network"public" | "private"NoPublic or private IPFS (default: "public")
expiresnumberNoExpiration time in seconds for private links (default: 600)
Example Prompts: 
Create a link for CID bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4

Generate a temporary download link for my private file with CID QmX...
Generate a temporary download link specifically for private IPFS files.
ParameterTypeRequiredDescription
cidstringYesThe CID of the private file
expiresnumberNoExpiration time in seconds (default: 600 = 10 minutes)
Example Prompt: 
Create a 30-minute download link for private CID bafkreih...

​
fetchFromGateway

Fetch content from IPFS via Pinata gateway and return it.
ParameterTypeRequiredDescription
cidstringYesThe CID of the file to fetch
network"public" | "private"NoPublic or private IPFS (default: "public")
Example Prompts: 
Fetch the content with CID QmX... from IPFS

Get the contents of my private file bafkreih...

​
Group Operations

​
listGroups

List groups in your Pinata account with optional filtering.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
namestringNoFilter groups by name
limitnumberNoMaximum number of results
pageTokenstringNoToken for pagination
Example Prompt: 
List all my Pinata groups

​
createGroup

Create a new group to organize files.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
namestringYesName for the new group
Example Prompt: 
Create a new group called "Project Assets" on Pinata

​
getGroup

Retrieve detailed information about a specific group.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
idstringYesThe unique ID of the group
Example Prompt: 
Get details for group abc123

​
updateGroup

Update metadata for an existing group.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
idstringYesThe unique ID of the group
namestringNoNew name for the group
Example Prompt: 
Rename group abc123 to "Marketing Assets"

​
deleteGroup

Delete a group from your Pinata account.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
idstringYesThe unique ID of the group
Example Prompt: 
Delete group abc123

​
addFileToGroup

Add an existing file to a group.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
groupIdstringYesThe ID of the group
fileIdstringYesThe ID of the file to add
Example Prompt: 
Add file xyz789 to group abc123

​
removeFileFromGroup

Remove a file from a group.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
groupIdstringYesThe ID of the group
fileIdstringYesThe ID of the file to remove
Example Prompt: 
Remove file xyz789 from group abc123

​
x402 Payment Instructions

Tools for content monetization using the x402 protocol. Currently supports USDC on Base and Base Sepolia.

​
createPaymentInstruction

Create payment requirements for gated content.
ParameterTypeRequiredDescription
namestringYesName for the payment instruction
pay_tostringYesWallet address (0x…) to receive payments
amount_usdcstringYesPrice in USD (e.g., "0.01" for 1 cent, "1.50" for $1.50)
network"base" | "base-sepolia"NoBlockchain network (default: "base")
descriptionstringNoDescription of the payment instruction
Example Prompt: 
Create a payment instruction called "Premium Content" that requires 0.01 USDC on Base to access, sending payments to 0x1234...

​
listPaymentInstructions

List and filter existing payment instructions.
ParameterTypeRequiredDescription
limitnumberNoLimit results
pageTokenstringNoToken for pagination
cidstringNoFilter by associated CID
namestringNoFilter by name
idstringNoFilter by specific ID
Example Prompt: 
List all my x402 payment instructions

​
getPaymentInstruction

Retrieve a specific payment instruction by ID.
ParameterTypeRequiredDescription
idstringYesThe payment instruction ID
Example Prompt: 
Get details for payment instruction pi_abc123

​
updatePaymentInstruction

Modify payment instruction settings.
ParameterTypeRequiredDescription
idstringYesThe payment instruction ID
namestringNoUpdated name
pay_tostringNoUpdated wallet address
amount_usdcstringNoUpdated price in USD
network"base" | "base-sepolia"NoUpdated network
descriptionstringNoUpdated description
Example Prompt: 
Update payment instruction pi_abc123 to charge $0.05 instead

​
deletePaymentInstruction

Remove a payment instruction.
ParameterTypeRequiredDescription
idstringYesThe payment instruction ID
Example Prompt: 
Delete payment instruction pi_abc123

​
listPaymentInstructionCids

List CIDs associated with a payment instruction.
ParameterTypeRequiredDescription
idstringYesThe payment instruction ID
limitnumberNoLimit results
pageTokenstringNoToken for pagination
Example Prompt: 
List all CIDs associated with payment instruction pi_abc123

​
addCidToPaymentInstruction

Associate a CID with a payment instruction for monetization.
ParameterTypeRequiredDescription
idstringYesThe payment instruction ID
cidstringYesThe CID to associate
Example Prompt: 
Add CID bafkreih... to payment instruction pi_abc123

​
removeCidFromPaymentInstruction

Remove a CID association from a payment instruction.
ParameterTypeRequiredDescription
idstringYesThe payment instruction ID
cidstringYesThe CID to remove
Example Prompt: 
Remove CID bafkreih... from payment instruction pi_abc123

​
CID Signatures

Tools for cryptographic content verification using EIP-712 signatures.

​
addSignature

Add an EIP-712 cryptographic signature to a CID for content verification.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
cidstringYesThe CID to sign
signaturestringYesThe EIP-712 signature
addressstringYesThe wallet address that created the signature
Example Prompt: 
Add signature 0xabc... from wallet 0x123... to CID bafkreih...

​
getSignature

Get signature details for a specific CID.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
cidstringYesThe CID to get the signature for
Example Prompt: 
Get the signature for CID bafkreih...

​
deleteSignature

Remove a signature from a CID.
ParameterTypeRequiredDescription
network"public" | "private"NoPublic or private IPFS (default: "public")
cidstringYesThe CID to remove the signature from
Example Prompt: 
Delete the signature from CID bafkreih...

​
Signed Upload URLs

​
createSignedUploadUrl

Create a presigned URL for client-side uploads without exposing your API key.
ParameterTypeRequiredDescription
expiresnumberYesHow long the URL is valid in seconds
max_file_sizenumberNoMax file size in bytes
allow_mime_typesstring[]NoAllowed MIME types (supports wildcards like "image/*")
group_idstringNoGroup to add the uploaded file to
filenamestringNoName for the uploaded file
keyvaluesobjectNoMetadata key-value pairs
Example Prompt: 
Create a signed upload URL that expires in 5 minutes and only allows image uploads up to 10MB

​
Pin by CID

​
pinByCid

Pin an existing CID from the IPFS network to your Pinata account.
ParameterTypeRequiredDescription
cidstringYesCID to pin
namestringNoCustom name for the file
group_idstringNoGroup to add the file to
keyvaluesobjectNoMetadata key-value pairs
host_nodesstring[]NoHost node IDs to fetch from
Example Prompt: 
Pin the CID bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4 to my account

​
queryPinRequests

Query the status of pin by CID requests.
ParameterTypeRequiredDescription
order"ASC" | "DESC"NoSort by date queued
statusstringNoFilter by status
cidstringNoFilter by CID
limitnumberNoLimit results
pageTokenstringNoToken for pagination
Example Prompt: 
Check the status of my pending pin requests

​
cancelPinRequest

Cancel a pending pin by CID request.
ParameterTypeRequiredDescription
idstringYesID of the pin request to cancel
Example Prompt: 
Cancel pin request pr_abc123

​
vectorizeFile

Vectorize a file for semantic search capabilities.
ParameterTypeRequiredDescription
file_idstringYesID of the file to vectorize
Example Prompt: 
Vectorize the file with ID abc123 so I can search it semantically

​
deleteFileVectors

Delete vectors for a file.
ParameterTypeRequiredDescription
file_idstringYesID of the file to delete vectors for
Example Prompt: 
Delete the vectors for file abc123

​
queryVectors

Query vectorized files using semantic search.
ParameterTypeRequiredDescription
group_idstringYesID of the group to search
textstringYesQuery string for semantic search
Example Prompt: 
Search my vectorized files in group xyz for "machine learning concepts"

​
Utilities

​
listAllowedDirectories

List directories the MCP server can access for file operations. Parameters: None Example Prompt: 
What directories can you access for file uploads?