Tools (6)

search_posts
get_profile
get_author_feed
get_post_thread
search_actors
report_feedback

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

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_posts",
    "arguments": {
      "query": "example"
    }
  }
}

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").

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_profile",
    "arguments": {
      "actor": "example"
    }
  }
}

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)

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_author_feed",
    "arguments": {
      "actor": "example"
    }
  }
}

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)

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_post_thread",
    "arguments": {
      "uri": "example"
    }
  }
}

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)

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_actors",
    "arguments": {
      "query": "example"
    }
  }
}

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

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "report_feedback",
    "arguments": {
      "feedback": "example"
    }
  }
}

Quick Start

Shell

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

Python

import httpx

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