Pinata MCP
OfficialFile & Folder Management: Upload, list, retrieve, update, and delete files and entire directories (folders) within Pinata.
Content Access & Distribution: Create direct gateway links, temporary private download links, and fetch content directly from the IPFS gateway.
Content Organization: Manage groups to organize files, including creating, updating, and deleting groups and managing file memberships.
Monetization (x402): Create and manage payment instructions (using USDC on Base/Base Sepolia) for gated content access.
Security & Verification: Implement cryptographic verification using EIP-712 signatures and manage signed upload URLs for secure client-side uploads.
AI & Search: Vectorize files for semantic search and query vectorized content within specified groups.
IPFS Interaction: Pin existing CIDs from the network and query the status of pin requests.
Provides access to both Public and Private IPFS through Pinata's API, enabling file uploads, searches, metadata management, group organization, and content retrieval from IPFS gateways.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Pinata MCP upload my project logo from the assets folder to Pinata as a private file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pinata-mcp
A Model Context Protocol (MCP) server that provides Claude with access to Pinata. This integration allows Claude to interact with Public and Private IPFS through Pinata's API.
Setup
Prerequisites
Node.js 20+ installed (uploads use
Fileandfs.openAsBlob, which Node.js 18 lacks)A Pinata account with an API key (JWT)
A Pinata Gateway URL
Installation
Installation will depend on whether you are using Claude Code or Claude Desktop.
The server is also published as @pinata/mcp, an alias of pinata-mcp: npx @pinata/mcp runs the same server, and either name works in the configs below.
Claude Code
Run claude mcp add and follow the prompts with the following information:
Server Name: pinata
Server Scope: Project or Global
Server Command: npx
Command Arguments: pinata-mcp /path/to/allowed/directory
Environment Variables: PINATA_JWT=<YOUR_JWT>,GATEWAY_URL=example.mypinata.cloudClaude Desktop
Add the following config to claude_desktop_config.json:
{
"mcpServers": {
"pinata": {
"command": "npx",
"args": [
"pinata-mcp",
"/path/to/allowed/directory",
"/another/allowed/directory"
],
"env": {
"PINATA_JWT": "<YOUR_JWT>",
"GATEWAY_URL": "example.mypinata.cloud"
}
}
}
}Note: The directory arguments are optional. If not provided, the server will only allow access to the current working directory. You can specify multiple directories to allow file access from multiple locations.
Related MCP server: SharePoint MCP Server
Available Tools
Authentication
Tool | Description |
| Verify that your Pinata JWT is valid and working |
File Operations
Tool | Description |
| Upload a file to Pinata (public or private IPFS). Files over 90 MiB use resumable uploads and can be any size. A large upload returns once Pinata has registered the file, which can take several minutes per GiB; the server reports progress every 15 seconds to clients that ask for it. If your client times out first, pass |
| Get your account's upload limits: |
| Search files by name, CID, or MIME type |
| Get detailed file information by ID |
| Update file metadata (name, key-values) |
| Delete a file from Pinata |
Folder Operations
Tool | Description |
| Upload a local directory as one folder with one CID, subdirectories included. Use it instead of |
| List one level of a folder: files and subdirectories with names, paths, sizes and CIDs, the folder's CID and root name, and whether files can still be added ( |
uploadFolder uploads every regular file under the directory, hidden files and empty files included. Paths in the folder are relative to the directory, so the folder's CID is the one ipfs add -r --cid-version 1 --raw-leaves <directory> computes (as long as the directory holds no empty subdirectories or symlinks, which a folder doesn't keep). A symlink to a file is followed only when its target is inside the allowed directories; symlinks to directories, symlinks leaving the allowed directories, empty directories, and names holding % are skipped and listed in the result. An empty directory, or a directory outside the allowed directories, is refused.
A folder holds at most folder_max_files files (getUploadLimits; 30,000 unless the account has its own limit). A new folder of more files is refused before any file is sent, and the error gives the file count of each top-level subdirectory: upload the directory as several folders, one uploadFolder call per subdirectory (directory set to it, with its own name). When files fail because a folder is full (adding files to it with folderId), the result gives the arguments that upload them as a new folder under another name instead of sending them into the full folder again.
A successful upload returns the folder's id, name, CID, file count, total size and duration:
{
"id": "019a8b2c-4d5e-7f60-8a1b-2c3d4e5f6a7b",
"name": "site",
"cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
"network": "public",
"files_uploaded": 25,
"files_in_folder": 25,
"total_bytes": 1831186,
"total_size": "1.7 MiB",
"duration_seconds": 35.9
}When some files fail for good, the other files stay in the folder and the result lists the failed paths with their reasons (the first 50), the folder id, and the arguments of a call that sends only the failed files again into the same folder:
{
"directory": "/path/to/allowed/directory/site",
"network": "public",
"name": "site",
"folderId": "019a8b2c-4d5e-7f60-8a1b-2c3d4e5f6a7b",
"paths": ["images/large.bin", "docs/guide.pdf"]
}The same folderId adds files to an existing folder, as long as name is the folder's name (its root in listFolder) and the folder is still appendable; a file whose path is already in the folder replaces it. For example, to add new/report.pdf from the same directory: { "directory": "/path/to/allowed/directory/site", "folderId": "…", "paths": ["new/report.pdf"] }.
listFolder lists one level at a time:
{ "folderId": "019a8b2c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "path": "images/2024", "limit": 100 }returns the folder's cid, root, appendable, appendable_until, entries (each with type file or directory, name, path, and for files size, cid and mime_type) and next_page_token, to pass as pageToken for the next page (null on the last).
Content Access
Tool | Description |
| Create a gateway link for public or private files |
| Generate a temporary download link for private files |
| Fetch content from IPFS via Pinata gateway |
Group Operations
Tool | Description |
| List groups with optional filtering |
| Create a new group for organizing files |
| Get group details by ID |
| Update group information |
| Delete a group |
| Add a file to a group |
| Remove a file from a group |
x402 Payment Instructions
Tools for content monetization using the x402 protocol:
Tool | Description |
| Create payment requirements for gated content |
| List/filter existing payment instructions |
| Get details of a specific payment instruction |
| Modify payment instruction settings |
| Remove a payment instruction |
| List CIDs associated with a payment instruction |
| Associate a CID with a payment instruction |
| Remove a CID association |
CID Signatures
Tools for cryptographic content verification using EIP-712 signatures:
Tool | Description |
| Add a cryptographic signature to a CID |
| Get signature details by CID |
| Remove a signature |
Signed Upload URLs
Tool | Description |
| Create a presigned URL for client-side uploads. |
Pin by CID
Tool | Description |
| Pin an existing CID from the IPFS network |
| Query the status of pin requests |
| Cancel a pending pin request |
Vectorize (AI/Semantic Search)
Tool | Description |
| Vectorize a file for semantic search |
| Delete vectors for a file |
| Query vectorized files using semantic search |
Utilities
Tool | Description |
| List directories the server can access for file operations |
Local Development
To test the MCP server locally during development:
1. Clone and install dependencies
git clone https://github.com/PinataCloud/pinata-mcp.git
cd pinata-mcp
npm install2. Build the project
npm run build3. Set up environment variables
The server reads PINATA_JWT and GATEWAY_URL from its environment; it does not load a .env file. Pass them in the MCP config (step 4), with -e for the MCP Inspector, or export them in your shell:
export PINATA_JWT=your_pinata_jwt_here
export GATEWAY_URL=your-gateway.mypinata.cloud4. Configure Claude to use the local build
Claude Code
Run claude mcp add with the local path:
Server Name: pinata-dev
Server Scope: Project
Server Command: node
Command Arguments: /path/to/pinata-mcp/dist/index.js /path/to/allowed/directory
Environment Variables: PINATA_JWT=<YOUR_JWT>,GATEWAY_URL=example.mypinata.cloudClaude Desktop
Update claude_desktop_config.json to point to your local build:
{
"mcpServers": {
"pinata-dev": {
"command": "node",
"args": [
"/path/to/pinata-mcp/dist/index.js",
"/path/to/allowed/directory"
],
"env": {
"PINATA_JWT": "<YOUR_JWT>",
"GATEWAY_URL": "example.mypinata.cloud"
}
}
}
}5. Testing changes
After making code changes:
Rebuild:
npm run buildRestart Claude Code or Claude Desktop to pick up the changes
Testing with MCP Inspector
Use the MCP Inspector to test the server:
Web UI (interactive debugging)
npx @modelcontextprotocol/inspector \
-e PINATA_JWT=your_jwt \
-e GATEWAY_URL=your-gateway.mypinata.cloud \
-- node dist/index.jsThis opens a browser UI where you can interactively list tools, call them with parameters, and inspect responses.
CLI mode (for scripting/CI)
# List all available tools
npx @modelcontextprotocol/inspector --cli --method tools/list \
-e PINATA_JWT=your_jwt \
-e GATEWAY_URL=your-gateway.mypinata.cloud \
-- node dist/index.js
# Call a specific tool
npx @modelcontextprotocol/inspector --cli --method tools/call \
--tool-name testAuthentication \
-e PINATA_JWT=your_jwt \
-e GATEWAY_URL=your-gateway.mypinata.cloud \
-- node dist/index.jsReleasing
Publishing a GitHub Release publishes the package to npm through the Release workflow (.github/workflows/release.yml).
Bump the version in
package.json(andpackage-lock.json) and push it tomain:npm version patch|minor|major --no-git-tag-version.Create a GitHub Release with the tag
v<version>(e.g.v0.3.1) on that commit. The workflow:checks that the tag matches
package.jsonand that the version isn't on npm yetwaits for approval of the
npm-publishenvironment, which onlymainandv*tags can deploy tobuilds and publishes with trusted publishing and provenance (no npm token). Releases marked as pre-release go to the
nextdist-tag, everything else tolatest.
npm version patch --no-git-tag-version
git commit -am "chore: release 0.3.1" && git push
gh release create v0.3.1 --generate-notes # add --prerelease for a "next" releaseThe @pinata/mcp alias
@pinata/mcp in packages/mcp-alias is a thin alias whose pinata-mcp command runs this package's server (see its README). It depends on pinata-mcp with >=0.5.0 <1.0.0, so new 0.x releases reach it without republishing. It only needs a release when the alias itself changes or pinata-mcp reaches 1.0.
To release it, bump version in packages/mcp-alias/package.json and push to main. .github/workflows/publish-mcp-alias.yml runs its test and publishes with trusted publishing, after approval of the npm-publish environment. The dist-tag comes from publishConfig.tag in that file.
Example Prompts for Claude
Test my Pinata connection:
"Test my Pinata authentication to make sure everything is working"
Upload an image to Pinata:
"Upload this image to my Pinata account as a private file named 'My Example Image'"
Search for files:
"Search my Pinata account for all PNG files"
Create a group and add files:
"Create a new group called 'Project Assets' on Pinata, then find all my JSON files and add them to this group"
Upload a folder:
"Upload the folder ~/projects/site to Pinata as a public folder named 'site', then list its images directory"
Fetch content from IPFS:
"Fetch the content with CID QmX... from IPFS"
Create a payment instruction for content monetization:
"Create a payment instruction called 'Premium Content' that requires 0.01 USDC on Base to access"
Pin an existing CID:
"Pin the CID bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4 to my account"
Vectorize files for AI search:
"Vectorize the file with ID abc123 so I can search it semantically"
Query vectorized content:
"Search my vectorized files in group xyz for 'machine learning concepts'"Available Tools
38 toolsaddCidToPaymentInstructionC
Associate a CID with a payment instruction for x402 monetization
Inputs: id (required), cid (required).
addFileToGroupC
Add an existing file to a group in your Pinata account
Inputs: fileId (required), groupId (required), network.
addSignatureB
Add an EIP-712 cryptographic signature to a CID for content verification
Inputs: cid (required), address (required), signature (required), network.
cancelPinRequestC
Cancel a pending pin by CID request
Inputs: id (required).
createGroupB
Create a new group in your Pinata account to organize files
Inputs: name (required), network.
createLinkA
Create a direct access link for a file stored on Pinata IPFS. For public files returns a gateway URL, for private files generates a temporary download link.
Inputs: cid (required), expires, network.
createPaymentInstructionA
Create a new x402 payment instruction for content monetization. Currently supports USDC (6 decimals) on Base/Base Sepolia only.
Inputs: name (required), pay_to (required), amount_usdc (required), network, +1 more.
createPrivateDownloadLinkA
Generate a temporary download link for accessing a private IPFS file from Pinata
Inputs: cid (required), expires.
createSignedUploadUrlB
Create a signed URL for client-side file uploads without exposing your API key
Inputs: expires (required), network, filename, group_id, +3 more.
deleteFileB
Delete a file from your Pinata account by its ID
Inputs: id (required), network.
deleteFileVectorsC
Delete vectors for a file
Inputs: file_id (required).
deleteGroupC
Delete a group from your Pinata account by its ID
Inputs: id (required), network.
deletePaymentInstructionC
Delete an x402 payment instruction
Inputs: id (required).
deleteSignatureC
Remove a signature from a CID
Inputs: cid (required), network.
fetchFromGatewayB
Fetch content from Public or Private IPFS via Pinata gateway and return it
Inputs: cid (required), network.
getFileByIdC
Retrieve detailed information about a specific file stored on Pinata by its ID
Inputs: id (required), network.
getGroupC
Retrieve detailed information about a specific group by its ID
Inputs: id (required), network.
getPaymentInstructionB
Retrieve a specific x402 payment instruction by ID
Inputs: id (required).
getSignatureC
Get signature details for a specific CID
Inputs: cid (required), network.
getUploadLimitsA
Get the upload limits of your Pinata account: folder_max_files, the most files one folder can hold (30,000 unless the account has its own limit). uploadFolder refuses a new folder of more files before sending any; upload such a directory as several folders.
Inputs: no named parameters.
listAllowedDirectoriesB
List all directories that this MCP server is allowed to access for file operations
Inputs: no named parameters.
listFolderA
List one level of a folder on Pinata (one uploaded with uploadFolder, or any other folder): its files and subdirectories with their names, paths, sizes and CIDs, plus the folder's CID, its root (the name every file path starts with) and whether files can still be added to it (appendable, appendable_until). Pass path to list a subdirectory, and next_page_token as pageToken for the next page.
Inputs: folderId (required), path, limit, network, +1 more.
listGroupsB
List groups in your Pinata account with optional filtering by name
Inputs: name, limit, network, pageToken.
listPaymentInstructionCidsB
List CIDs associated with a payment instruction
Inputs: id (required), limit, pageToken.
listPaymentInstructionsB
List and filter x402 payment instructions for content monetization
Inputs: id, cid, name, limit, +1 more.
pinByCidC
Pin an existing CID from the IPFS network to your Pinata account
Inputs: cid (required), name, group_id, keyvalues, +1 more.
queryPinRequestsB
Query the status of pin by CID requests
Inputs: cid, limit, order, status, +1 more.
queryVectorsB
Query vectorized files in a group using semantic search
Inputs: text (required), group_id (required).
removeCidFromPaymentInstructionC
Remove a CID association from a payment instruction
Inputs: id (required), cid (required).
removeFileFromGroupC
Remove a file from a group in your Pinata account
Inputs: fileId (required), groupId (required), network.
searchFilesC
Search for files in your Pinata account by name, CID, or MIME type. Returns a list of files matching the given criteria.
Inputs: cid, name, limit, network, +2 more.
testAuthenticationB
Verify that your Pinata JWT is valid and working
Inputs: no named parameters.
updateFileC
Update metadata for an existing file on Pinata including name and key-value pairs
Inputs: id (required), name, network, keyvalues.
updateGroupB
Update metadata for an existing group on Pinata
Inputs: id (required), name, network.
updatePaymentInstructionB
Update an existing x402 payment instruction. Currently supports USDC (6 decimals) on Base/Base Sepolia only.
Inputs: id (required), name, pay_to, network, +2 more.
uploadFileA
Upload a file to Pinata IPFS. Provide either a file:// URI or base64-encoded content. Files over 90 MiB are sent as resumable uploads, and by default the call returns only once Pinata has registered the file, which for a large file can take several minutes per GiB after the last byte. Progress is reported every 15 seconds to clients that ask for it. If your client times out on long calls, pass waitForCid: false for large files and find the file later with searchFiles by name or CID.
Inputs: network, fileName, group_id, mimeType, +4 more.
uploadFolderA
Upload a local directory to Pinata IPFS as one folder with one CID, keeping its subdirectories. Use this instead of uploadFile when the content is a directory (a website, a dataset, a set of images); use uploadFile for a single file. Every regular file under the directory is sent as its own resumable upload, several at a time, each retried on its own, so a large folder or a flaky connection does not restart from zero. Symlinks are followed only to files inside the allowed directories; skipped entries are listed in the result. When some files fail, the result names them and gives the arguments that send only those files again into the same folder (folderId + paths). Also adds files to an existing folder: pass its folderId and its name (listFolder shows it as root). A folder holds at most folder_max_files files (see getUploadLimits; 30,000 unless the account has its own limit): a new folder of more files is refused before any is sent, with the file count of each top-level subdirectory, so the directory can be uploaded as several folders, one call per subdirectory (directory set to it, with its own name). Progress is reported per file to clients that ask for it.
Inputs: directory (required), name, paths, network, +5 more.
vectorizeFileC
Vectorize a file for AI/semantic search capabilities
Inputs: file_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 38 tools
Most tools map to distinct resource/action pairs across files, folders, groups, payments, signatures, vectors, and gateway access. However, createLink and createPrivateDownloadLink overlap for private-file links, and uploadFile/uploadFolder/createSignedUploadUrl require careful reading to distinguish. The large surface slightly increases misselection risk, but descriptions generally clarify boundaries.
All tool names use camelCase and start with clear verbs such as create, get, list, update, delete, add, remove, query, upload, and fetch. Minor variants like pinByCid and fetchFromGateway remain predictable and readable. There is no mixing of snake_case or inconsistent casing conventions.
The server exposes 38 tools, which is heavy for a single MCP surface and spans many subdomains: files, folders, groups, vectors, payments, signatures, auth, and gateway access. Even if most tools are purposeful, this exceeds a well-scoped surface and raises context and selection costs. The count is more like a full API client than a focused MCP tool set.
Core file lifecycle operations are well covered (upload, search/get, update, delete), and groups, payments, and signatures have substantial CRUD coverage. Notable gaps remain: there is no obvious way to list files within a group, folder operations lack update/delete/rename coverage, and signatures/vectors have limited listing beyond specific get/query calls. Agents can work around some gaps but will hit dead ends for common folder/group management tasks.
Maintenance
Related MCP Connectors
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Read, edit, publish, and preview your pepita websites from Claude.
Give Claude only the Google Drive files you choose. Every action logged.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides full CRUD access to Pipedrive CRM API, enabling Claude and other LLM applications to manage deals, persons, organizations, activities, notes, and leads with advanced filtering and fuzzy search capabilities.6MIT
- AlicenseAqualityDmaintenanceProvides Claude with access to Microsoft SharePoint via the Microsoft Graph API, enabling folder management, document operations (upload, download, read, update, delete), and metadata management with secure OAuth 2.0 authentication.161MIT
- AlicenseNot gradedqualityDmaintenanceConnects Claude to your self-hosted or cloud-based Seafile storage for managing libraries and files through natural language. It enables users to browse directories, read file contents, and perform file operations like moving, renaming, or searching across their private infrastructure.4MIT
- AlicenseAqualityDmaintenanceEnables LLMs like Claude to interact with Pipedrive CRM data through a standardized interface, providing 22 tools for managing deals, persons, organizations, activities, and more.221MIT