Skip to content

Claude Desktop

Claude Desktop is the recommended host for Picora MCP integration. It supports both transport modes natively.

This page covers both setup paths. Pick HTTP OAuth unless you have a reason to run locally.

Mode comparison

HTTP OAuth (recommended)stdio (npm)
Setup complexityAdd 5 lines to config + click “Authorize”Install npm package + config + API Key
Multi-device syncSame OAuth grant works everywhereEach device needs its own API Key
Network requirementAlways (talks to mcp.picora.me)Only when AI calls a tool
UpdatesAuto-updated server-sidenpm update -g @picora/mcp
Best forMost usersPower users, offline scenarios

1. Open Claude Desktop config

PlatformPath
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json

If the file doesn’t exist, create it.

2. Add the Picora server

{
  "mcpServers": {
    "picora": {
      "url": "https://mcp.picora.me",
      "transport": "http"
    }
  }
}

For mainland China users, use https://mcp.picora.cn.

If you already have other MCP servers configured, add "picora": { ... } as a sibling.

3. Restart Claude Desktop

After saving config, fully quit Claude Desktop (Cmd+Q on Mac / right-click → Exit on Windows) and restart.

4. Authorize

Click the 🔌 plug icon at the bottom of any conversation. You should see “picora” listed. Click Authorize — a browser window opens to Picora’s consent page.

On the consent screen:

  • Review the requested scopes (default: media:read media:write media:delete docs:read docs:write docs:delete usage:read)
  • Untick any scope you don’t want to grant
  • Click Authorize

Browser redirects back; Claude Desktop confirms the connection.

5. Test it

In a new chat, type:

“List my recent images on Picora.”

Claude should call list_media and respond with a table of your images.

stdio (npm) setup

1. Install the npm package globally

Terminal window
npm install -g @picora/mcp

This installs picora-mcp to your global PATH.

2. Get an API Key

  1. Open Settings → API Keys
  2. Click Create new key
  3. Name it (e.g., “Claude Desktop on MacBook Pro”)
  4. Pick scopes (default: all read/write, no delete — recommended)
  5. Copy the displayed key

3. Add to Claude Desktop config

Open the config file (paths above) and add:

{
  "mcpServers": {
    "picora": {
      "command": "npx",
      "args": ["-y", "@picora/mcp"],
      "env": {
        "PICORA_API_KEY": "sk_live_YOUR_KEY",
        "PICORA_API_URL": "https://api.picora.me"
      }
    }
  }
}

For mainland China, use https://api.picora.cn.

4. Restart Claude Desktop and test

Same as HTTP mode step 5.

Verifying connection

After connecting, the plug icon at the bottom of the conversation shows connected MCP servers. Click it; “picora” should appear with a list of available tools (12 in total — upload_image, upload_video, upload_audio, upload_doc, list_media, list_docs, etc.).

If the icon is empty or shows an error, check:

  • Claude Desktop log file (~/Library/Logs/Claude/mcp.log on Mac)
  • Config JSON syntax (use jsonlint if uncertain)
  • Network connectivity to mcp.picora.me or api.picora.me

Switching modes

Already on stdio and want to switch to HTTP OAuth (or vice versa):

  1. Edit config: replace the picora entry with the new mode’s syntax
  2. Restart Claude Desktop
  3. Authorize (HTTP) or test (stdio)

You can keep both modes simultaneously by giving them different keys (e.g., picora-local and picora-cloud), but it’ll confuse the AI — pick one.

Troubleshooting

”Server not connected” / plug icon empty

  • Verify config JSON syntax
  • Restart Claude Desktop fully (not just close window)
  • Check the log file for specific errors

”Authorization failed” (HTTP mode)

  • The OAuth state parameter may have expired (>10 min between starting and completing). Retry.
  • Check that you’re logged in at center.picora.me in your default browser.
  • If using a corporate browser with strict cookie policies, try in a personal profile.

”API Key invalid” (stdio mode)

  • Verify you copied the full sk_live_... value (40 chars, no extra whitespace)
  • Check the key is still active (not revoked) at Settings → API Keys
  • Confirm PICORA_API_URL matches your account platform (.me for overseas, .cn for mainland)

Tools missing from the menu

  • Some scopes may not have been granted (HTTP mode) — re-authorize and grant the missing scopes
  • For stdio: API Key may have limited scopes — create a new key with broader scopes

”Quota exceeded” errors when using a tool

  • Your account hit a quota limit (storage, bandwidth, doc count). Visit Dashboard → Usage to see what’s full and either delete resources or upgrade.

Revoking access

HTTP OAuth

  1. Go to Settings → Authorized apps
  2. Find the Claude Desktop entry
  3. Click Revoke

Claude Desktop will be prompted to re-authorize next time it tries to use Picora.

stdio

Just revoke the API Key from Settings → API Keys. Claude will get 401 errors and you can remove the entry from config.