bluesky-mcp-server

Get Bluesky Profile

bsky_get_profile

Read-onlyIdempotent

Fetch a Bluesky actor's public profile by handle (e.g. "bsky.app") or DID (e.g. "did:plc:z72i7hdynmk6r22z27h6tvur"). Returns displayName, handle, DID, bio, pronouns, website, follower/following/post counts, avatar URL, moderation labels, pinned post AT-URI, and Bluesky verification — whether the account is verified or a trusted verifier, and who verified it. Use this as the first step to resolve a handle to a DID before calling tools that require a DID or AT-URI. Handles and DIDs are interchangeable as input, and "@bsky.app" or the account's bsky.app page (https://bsky.app/profile/bsky.app) work as-is.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`actor`	Yes	Handle (e.g. "bsky.app", "alice.bsky.social") or DID (e.g. "did:plc:z72i7hdynmk6r22z27h6tvur") of the actor to look up. A leading "@" ("@bsky.app") and the account's bsky.app page ("https://bsky.app/profile/bsky.app") are accepted and read as the handle or DID they carry. A bare name without a dot is not a handle — use bsky_search_actors to resolve one.

Output Schema

TableJSON Schema

Name	Required	Description
`did`	No	Decentralized Identifier — the permanent, portable identity key for this account.
`error`	No	Present when the call failed. Absent on success.
`avatar`	No	URL of the profile avatar image.
`handle`	No	Human-readable username, e.g. "alice.bsky.social".
`labels`	No	Moderation labels applied to this profile.
`website`	No	URL the account set as its website, in the profile field of that name rather than in the bio. Absent when it set none. The one link on a profile that points somewhere else — follow it before reading the bio for one.
`pronouns`	No	Free-form pronouns the account set, e.g. "they/he". Absent when it set none. Account-authored text bounded only by length, not a fixed vocabulary — read it as written rather than parsing it.
`createdAt`	No	ISO 8601 timestamp of account creation.
`indexedAt`	No	ISO 8601 timestamp when the AppView last indexed this profile.
`postsCount`	No	Total posts authored by this actor.
`description`	No	Biography / about text.
`displayName`	No	Display name set by the user. May differ from the handle.
`followsCount`	No	Number of accounts this actor follows.
`verification`	No	Bluesky verification state — what tells a verified account from a look-alike handle. Absent when Bluesky sent none, which it does for an account neither verified nor a trusted verifier.
`pinnedPostUri`	No	AT-URI of the pinned post, if any. Pass to bsky_get_post_thread to read it.
`followersCount`	No	Number of accounts following this actor.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 25, 2026

addedOutput schema / properties / verification

Added value: +{
+  "additionalProperties": false,
+  "description": "Bluesky verification state — what tells a verified account from a look-alike handle. Absent when Bluesky sent none, which it does for an account neither verified nor a trusted verifier.",
+  "properties": {
+    "trustedVerifierStatus": {
+      "description": "Whether this account is itself a trusted verifier, whose verifications Bluesky honors — same values as verifiedStatus.",
+      "type": "string"
+    },
+    "verifications": {
+      "description": "Verifications issued by trusted verifiers — empty for an account that verifies others but was never verified itself.",
+      "items": {
+        "additionalProperties": false,
+        "description": "One verification a trusted verifier issued for this account.",
+        "properties": {
+          "createdAt": {
+            "description": "ISO 8601 timestamp when it was issued.",
+            "type": "string"
+          },
+          "isValid": {
+            "description": "Whether this verification still holds.",
+            "type": "boolean"
+          },
+          "issuer": {
+            "description": "DID of the trusted verifier that issued it.",
+            "type": "string"
+          },
+          "issuerDisplayName": {
+            "description": "Display name of the issuer, when Bluesky sent it. Account-authored text.",
+            "type": "string"
+          },
+          "issuerHandle": {
+            "description": "Handle of the issuer, when Bluesky sent it.",
+            "type": "string"
+          },
+          "uri": {
+            "description": "AT-URI of the verification record.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "issuer",
+          "uri",
+          "isValid",
+          "createdAt"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "verifiedStatus": {
+      "description": "Whether a trusted verifier verified this account: \"valid\", \"invalid\" (verified once, no longer holds), or \"none\". Passed through as Bluesky sends it, so another value may appear.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "verifiedStatus",
+    "trustedVerifierStatus",
+    "verifications"
+  ],
+  "type": "object"
+}

Changed3 schema fields changedSep 25, 2026

changedInput schema / properties / actor / description

Previous value: -"Handle (e.g. \"bsky.app\", \"alice.bsky.social\") or DID (e.g. \"did:plc:z72i7hdynmk6r22z27h6tvur\") of the actor to look up. A bare name without a dot is not a handle — use bsky_search_actors to resolve one."New value: +"Handle (e.g. \"bsky.app\", \"alice.bsky.social\") or DID (e.g. \"did:plc:z72i7hdynmk6r22z27h6tvur\") of the actor to look up. A leading \"@\" (\"@bsky.app\") and the account's bsky.app page (\"https://bsky.app/profile/bsky.app\") are accepted and read as the handle or DID they carry. A bare name without a dot is not a handle — use bsky_search_actors to resolve one."

changedInput schema / properties / actor / maxLength
```
Previous value: -253New value: +2048
```

changedInput schema / properties / actor / pattern

Previous value: -"^(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-])$"New value: +"^(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-]|@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|https:\\/\\/bsky\\.app\\/profile\\/(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-])\\/?(?:[?#].*)?)$"

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "did",
+      "handle"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `actor_not_found`: The handle does not resolve or the profile does not exist. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "actor_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "did",
-  "handle"
-]

Changed2 schema fields changedJul 31, 2026

addedOutput schema / properties / pronouns

Added value: +{
+  "description": "Free-form pronouns the account set, e.g. \"they/he\". Absent when it set none. Account-authored text bounded only by length, not a fixed vocabulary — read it as written rather than parsing it.",
+  "type": "string"
+}

addedOutput schema / properties / website

Added value: +{
+  "description": "URL the account set as its website, in the profile field of that name rather than in the bio. Absent when it set none. The one link on a profile that points somewhere else — follow it before reading the bio for one.",
+  "type": "string"
+}

Changed3 schema fields changedJul 31, 2026

changedInput schema / properties / actor / description

Previous value: -"Handle (e.g. \"bsky.app\", \"alice.bsky.social\") or DID (e.g. \"did:plc:z72i7hdynmk6r22z27h6tvur\") of the actor to look up."New value: +"Handle (e.g. \"bsky.app\", \"alice.bsky.social\") or DID (e.g. \"did:plc:z72i7hdynmk6r22z27h6tvur\") of the actor to look up. A bare name without a dot is not a handle — use bsky_search_actors to resolve one."

addedInput schema / properties / actor / minLength
```
Added value: +1
```

addedInput schema / properties / actor / pattern

Added value: +"^(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-])$"

First observedJun 7, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds value by detailing what data is returned (including verification status, moderation labels, pinned post AT-URI), which goes beyond the structured annotations. It does not contradict annotations and provides a clear, non-redundant behavioral context. It could mention rate limits or error conditions, but for a read-only, idempotent tool this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long but every sentence earns its place. It starts with the core purpose, lists return fields, and then gives practical usage guidance. The structure is logical and front-loaded, with the primary action and input formats mentioned early. It is not bloated; the length is justified by the amount of useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one required parameter) and the existence of an output schema, the description is exceptionally complete. It covers accepted input formats, the return payload (listing many fields), and the recommended usage pattern (handle-to-DID resolution). It even provides a fallback to a sibling tool for bare names. There is nothing an agent needs to know to call this tool correctly that is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter 'actor' is fully documented in the schema, including accepted formats (handle, DID, @handle, URL). The tool description repeats this information and adds the context that handles and DIDs are interchangeable, but this is essentially a restatement of the schema's description. Since the schema already carries the semantic load, the description adds marginal new meaning, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Fetch a Bluesky actor's public profile by handle or DID.' It enumerates the specific return fields (displayName, handle, DID, bio, etc.), making the purpose unambiguous and distinct from sibling tools that fetch feeds or posts. The resource and action are specific, and it even explains the use case for resolving a handle to a DID.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool: 'Use this as the first step to resolve a handle to a DID before calling tools that require a DID or AT-URI.' It also provides an exclusion in the schema description: 'A bare name without a dot is not a handle — use bsky_search_actors to resolve one.' This direct routing to an alternative is exactly what usage guidelines should do.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All bluesky-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.