Tutorial: Bluesky - Gnist Context

Media

Data source: Bluesky (AT Protocol)

Overview

Bluesky wraps Bluesky (AT Protocol), handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-bluesky": {
      "url": "https://context.gnist.ai/mcp/bluesky/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`search_posts`

Search Bluesky posts by keyword. Returns matching posts with author handles, text content, timestamps, and engagement counts (replies, reposts, likes). Use sort="top" for most popular results.

Parameter	Type	Required	Description
`query`	string	required	Search query for Bluesky posts (e.g. "AI agents", "climate change").
`limit`	integer	optional	Max results to return (1-100). Default 10. (default: `10`)
`sort`	string	optional	Sort order: "latest" or "top". Default "latest". (default: `latest`)

curl -X POST "https://context.gnist.ai/mcp/bluesky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_posts", "arguments": {"query": "AI agents"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bluesky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'AI agents'}, 'name': 'search_posts'}},
)
print(resp.json())

`get_profile`

Get a Bluesky user profile by handle or DID. Returns display name, description, avatar URL, follower/following counts, post count, and account creation date.

Parameter	Type	Required	Description
`actor`	string	required	Bluesky handle (e.g. "bsky.app") or DID (e.g. "did:plc:z72i7hdynmk6r22z27h6tvur").

curl -X POST "https://context.gnist.ai/mcp/bluesky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_profile", "arguments": {"actor": "bsky.app"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bluesky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'actor': 'bsky.app'}, 'name': 'get_profile'}},
)
print(resp.json())

`get_author_feed`

Get recent posts from a Bluesky user. Returns the user's latest posts with text content, timestamps, and engagement counts. Use get_profile() first to verify the handle exists.

Parameter	Type	Required	Description
`actor`	string	required	Bluesky handle (e.g. "bsky.app") or DID.
`limit`	integer	optional	Max posts to return (1-100). Default 10. (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/bluesky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_author_feed", "arguments": {"actor": "bsky.app"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bluesky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'actor': 'bsky.app'}, 'name': 'get_author_feed'}},
)
print(resp.json())

`get_post_thread`

Get a post thread by AT URI, including replies. Returns the root post and a flattened list of replies. Use URIs from search_posts() or get_author_feed() results.

Parameter	Type	Required	Description
`uri`	string	required	AT Protocol URI of the post (e.g. "at://did:plc:.../app.bsky.feed.post/abc123").
`depth`	integer	optional	Max reply depth to fetch (0-100). Default 6. (default: `6`)

curl -X POST "https://context.gnist.ai/mcp/bluesky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_post_thread", "arguments": {"uri": "at://did:plc:.../app.bsky.feed.post/abc123"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bluesky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'uri': 'at://did:plc:.../app.bsky.feed.post/abc123'},
            'name': 'get_post_thread'}},
)
print(resp.json())

`search_actors`

Search Bluesky users by name or handle. Returns matching user profiles with handles, display names, descriptions, and follower counts.

Parameter	Type	Required	Description
`query`	string	required	Search query for Bluesky users (e.g. "bluesky", "journalist").
`limit`	integer	optional	Max results to return (1-100). Default 10. (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/bluesky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_actors", "arguments": {"query": "bluesky"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bluesky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'bluesky'}, 'name': 'search_actors'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/bluesky/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bluesky/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_posts to find items, then get_profile to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Bluesky provide?

Bluesky social network — search posts, view profiles, browse feeds via the AT Protocol public API. It exposes 6 tools: search_posts, get_profile, get_author_feed, get_post_thread, search_actors, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Bluesky API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.