Skip to main content
Glama

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 File and fs.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.cloud

Claude 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

testAuthentication

Verify that your Pinata JWT is valid and working

File Operations

Tool

Description

uploadFile

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 waitForCid: false to return once the bytes are stored, then find the file with searchFiles

getUploadLimits

Get your account's upload limits: folder_max_files, the most files one folder can hold (30,000 unless the account has its own limit)

searchFiles

Search files by name, CID, or MIME type

getFileById

Get detailed file information by ID

updateFile

Update file metadata (name, key-values)

deleteFile

Delete a file from Pinata

Folder Operations

Tool

Description

uploadFolder

Upload a local directory as one folder with one CID, subdirectories included. Use it instead of uploadFile whenever the content is a directory (a website, a dataset, a set of images). Each file is its own resumable upload, several at a time (concurrency, default 4), each retried on its own. Accepts network, name (defaults to the directory's name), group_id, keyvalues, cidVersion, folderId (upload into an existing folder) and paths (only these files, relative to the directory). Reports progress per file to clients that ask for it

listFolder

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 (appendable, appendable_until). Accepts path for a subdirectory, limit and pageToken

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

createLink

Create a gateway link for public or private files

createPrivateDownloadLink

Generate a temporary download link for private files

fetchFromGateway

Fetch content from IPFS via Pinata gateway

Group Operations

Tool

Description

listGroups

List groups with optional filtering

createGroup

Create a new group for organizing files

getGroup

Get group details by ID

updateGroup

Update group information

deleteGroup

Delete a group

addFileToGroup

Add a file to a group

removeFileFromGroup

Remove a file from a group

x402 Payment Instructions

Tools for content monetization using the x402 protocol:

Tool

Description

createPaymentInstruction

Create payment requirements for gated content

listPaymentInstructions

List/filter existing payment instructions

getPaymentInstruction

Get details of a specific payment instruction

updatePaymentInstruction

Modify payment instruction settings

deletePaymentInstruction

Remove a payment instruction

listPaymentInstructionCids

List CIDs associated with a payment instruction

addCidToPaymentInstruction

Associate a CID with a payment instruction

removeCidFromPaymentInstruction

Remove a CID association

CID Signatures

Tools for cryptographic content verification using EIP-712 signatures:

Tool

Description

addSignature

Add a cryptographic signature to a CID

getSignature

Get signature details by CID

deleteSignature

Remove a signature

Signed Upload URLs

Tool

Description

createSignedUploadUrl

Create a presigned URL for client-side uploads. network (public or private) fixes where every upload through the URL goes; left out, the upload's own network field decides (private if it sends none)

Pin by CID

Tool

Description

pinByCid

Pin an existing CID from the IPFS network

queryPinRequests

Query the status of pin requests

cancelPinRequest

Cancel a pending pin request

Tool

Description

vectorizeFile

Vectorize a file for semantic search

deleteFileVectors

Delete vectors for a file

queryVectors

Query vectorized files using semantic search

Utilities

Tool

Description

listAllowedDirectories

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 install

2. Build the project

npm run build

3. 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.cloud

4. 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.cloud

Claude 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:

  1. Rebuild: npm run build

  2. Restart 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.js

This 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.js

Releasing

Publishing a GitHub Release publishes the package to npm through the Release workflow (.github/workflows/release.yml).

  1. Bump the version in package.json (and package-lock.json) and push it to main: npm version patch|minor|major --no-git-tag-version.

  2. 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.json and that the version isn't on npm yet

    • waits for approval of the npm-publish environment, which only main and v* tags can deploy to

    • builds and publishes with trusted publishing and provenance (no npm token). Releases marked as pre-release go to the next dist-tag, everything else to latest.

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" release

The @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 tools
addCidToPaymentInstructionC

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.

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.

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

    B3.1/5.0

    Scored across 38 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects 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.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables LLMs like Claude to interact with Pipedrive CRM data through a standardized interface, providing 22 tools for managing deals, persons, organizations, activities, and more.
      22
      1
      MIT