Pinmetric MCP Documentation

Authentication

Create an MCP token from your profile page and send it with:

Authorization: Bearer pmcp_***

Config.toml

Codex streamable HTTP MCP configuration:

[mcp_servers.pinmetric]
url = "https://mcp.pinmetric.com/mcp"
bearer_token_env_var = "PINMETRIC_MCP_TOKEN"

Protocol

Field	Value	Notes
`Transport`	Streamable HTTP	Single MCP endpoint over HTTPS.
`Protocol Version`	2025-06-18	Returned by `initialize`.
`Lifecycle`	`initialize` -> `tools/list` -> `tools/call`	Standard JSON-RPC MCP flow.

Available Tools

Tool	Purpose	Inputs
`hello`	Returns an authenticated greeting for smoke testing.	`name` optional
`idea.popular`	Returns most popular ideas ordered by volume.	`limit` optional
`idea.search`	Searches ideas with prefix matching.	`query` required, `limit` optional
`account.get`	Returns Pinterest account detail by username.	`username` required
`account.search`	Searches accounts by username or full name.	`query` required, `limit` optional
`account.popular`	Returns popular accounts ordered by follower count.	`limit` optional
`pin.get`	Returns pin detail by internal id, Pinterest pin id, or Pinterest pin URL.	`id`, `pinId`, or `url`

Example Request - idea.search

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "idea.search",
    "arguments": {
      "query": "bedroom",
      "limit": 5
    }
  }
}

Example Request - account.get

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "account.get",
    "arguments": {
      "username": "pinterest"
    }
  }
}

Example Request - pin.get

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "pin.get",
    "arguments": {
      "url": "https://www.pinterest.com/pin/1234567890/"
    }
  }
}

Example Response Shape - idea.search

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 5 ideas for 'bedroom'."
      }
    ],
    "structuredContent": {
      "ideas": [
        {
          "id": 123,
          "keyword": "bedroom ideas",
          "pinClickId": "949806337612",
          "volume": 18100
                        }
                      ]
                    }
                  }
}

Example Response Shape - account.get

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Returned account detail for 'pinterest'."
      }
    ],
    "structuredContent": {
      "found": true,
      "username": "pinterest",
      "account": {
        "id": 42,
        "username": "pinterest",
        "fullName": "Pinterest",
        "pinCount": 12000,
        "boardCount": 80,
        "followerCount": 5000000,
        "domainVerified": true
      }
    }
  }
}

Example Response Shape - pin.get

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Returned pin detail for '1234567890'."
      }
    ],
    "structuredContent": {
      "found": true,
      "pin": {
        "id": 987,
        "pinId": "1234567890",
        "title": "Small bedroom storage ideas",
        "description": "Storage ideas for small bedrooms.",
        "imagePath": "https://i.pinimg.com/...",
        "link": "https://example.com/small-bedroom",
        "username": "pinterest",
        "boardName": "Bedroom Ideas",
        "commentCount": 14,
        "reactionCount": 320,
        "saveCount": 2800,
        "dominantColor": "#b8a48f"
      },
      "account": {
        "id": 42,
        "username": "pinterest",
        "followerCount": 5000000
      },
      "ideas": [
        {
          "id": 123,
          "keyword": "bedroom ideas",
          "pinClickId": "949806337612",
          "volume": 18100
        }
      ]
    }
  }
}

If a pin or account is not found, the tool returns found=false with a null object instead of treating the lookup as a server error.

MCP Documentation

Server