Skip to main content
Glama
Sign In
facebook-mcp

facebook-mcp

by IvanBBaev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Create Photo Post

facebook_create_photo_post

Publish one photo to a Facebook Page with optional caption, draft or scheduled timing, album placement, and dry-run preview by default.

Instructions

Publish ONE photo to a Page, optionally with a caption, as a draft, or scheduled, and optionally into one of the Page albums (album_id). The photo is either an https:// URL Meta fetches itself or a local file inside FB_MEDIA_DIR. Dry run by default.

Input Schema

NameRequiredDescriptionDefault
applyNoSet true to actually perform the write. Omitted or false ⇒ the server decides from its configured write mode: usually a dry run that returns a plan preview and changes nothing, but a server (or package) configured apply-first performs the write. To be certain nothing happens, read the result: a dry run always reports the plan and says the write was NOT performed.
photoYesThe image: an https:// URL Meta fetches itself (no credentials in the URL), or a local file path inside FB_MEDIA_DIR whose bytes this server uploads.
captionNoText shown with the photo. Unicode and emoji pass through unchanged.
plan_idNoThe `planId` returned by a preceding dry-run preview of this same tool. Required for irreversible and spend-tier writes; plans expire a few minutes after they are created.
profileNoPage profile key (e.g. "brand-a") or a raw Page ID. Omitted ⇒ the default Page (FB_PAGE_ID).
album_idNoUpload into this album instead of the Page's default Timeline Photos album. The album must belong to the Page, accept uploads, and be a normal or app album (not profile/cover).
alt_textNoAlt text for screen readers, up to 1000 characters. Omitted ⇒ no custom alt text is sent.
publishedNofalse ⇒ create the post UNPUBLISHED (a draft that stays invisible until facebook_update_post action:"publish_now"). Omitted or true ⇒ publish immediately. Must be omitted when scheduled_publish_time is set.
targetingNoWho sees the post in Feed: geo_locations and/or age_min. Narrows distribution only — the post stays publicly reachable by link and on the Page.
page_timezoneNoIANA timezone name of the Page (e.g. "Europe/Sofia"), used only to echo a scheduled instant in Page-local time next to UTC. Omitted ⇒ the server reads the Page's own timezone; if that read fails the echo is UTC-only.
scheduled_publish_timeNoWhen to publish, as an ISO-8601 instant WITH an explicit offset — "2026-08-01T09:30:00+03:00" or "2026-08-01T06:30:00Z". A bare local time ("2026-08-01T09:30:00") and a raw epoch number are both REFUSED, because they have no unambiguous meaning. Must be at least 10 minutes and at most 75 days ahead. Setting this creates the post unpublished; do NOT also pass published:true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.8.0
    • addedInput schema / properties / album_id
      Added value: +{
+  "description": "Upload into this album instead of the Page's default Timeline Photos album. The album must belong to the Page, accept uploads, and be a normal or app album (not profile/cover).",
+  "minLength": 1,
+  "pattern": "^(?=.*\\w)[\\w.-]+$",
+  "type": "string"
+}
    • addedInput schema / properties / alt_text
      Added value: +{
+  "description": "Alt text for screen readers, up to 1000 characters. Omitted ⇒ no custom alt text is sent.",
+  "maxLength": 1000,
+  "minLength": 1,
+  "type": "string"
+}
    • changedInput schema / properties / scheduled_publish_time / description
      Previous value: -"When to publish, as an ISO-8601 instant WITH an explicit offset — \"2026-08-01T09:30:00+03:00\" or \"2026-08-01T06:30:00Z\". A bare local time (\"2026-08-01T09:30:00\") and a raw epoch number are both REFUSED, because they have no unambiguous meaning. Must be more than 10 minutes and at most 75 days ahead. Setting this creates the post unpublished; do NOT also pass published:true."New value: +"When to publish, as an ISO-8601 instant WITH an explicit offset — \"2026-08-01T09:30:00+03:00\" or \"2026-08-01T06:30:00Z\". A bare local time (\"2026-08-01T09:30:00\") and a raw epoch number are both REFUSED, because they have no unambiguous meaning. Must be at least 10 minutes and at most 75 days ahead. Setting this creates the post unpublished; do NOT also pass published:true."
    • addedInput schema / properties / targeting
      Added value: +{
+  "additionalProperties": false,
+  "description": "Who sees the post in Feed: geo_locations and/or age_min. Narrows distribution only — the post stays publicly reachable by link and on the Page.",
+  "properties": {
+    "age_min": {
+      "anyOf": [
+        {
+          "const": 13,
+          "type": "number"
+        },
+        {
+          "const": 15,
+          "type": "number"
+        },
+        {
+          "const": 18,
+          "type": "number"
+        },
+        {
+          "const": 21,
+          "type": "number"
+        },
+        {
+          "const": 25,
+          "type": "number"
+        }
+      ],
+      "description": "Minimum viewer age: 13, 15, 18, 21 or 25."
+    },
+    "geo_locations": {
+      "additionalProperties": false,
+      "properties": {
+        "cities": {
+          "description": "City location ids as [{key:\"...\"}], from Ads Manager targeting search.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "key": {
+                "pattern": "^\\d+$",
+                "type": "string"
+              }
+            },
+            "required": [
+              "key"
+            ],
+            "type": "object"
+          },
+          "maxItems": 250,
+          "type": "array"
+        },
+        "countries": {
+          "description": "Uppercase ISO country codes, e.g. [\"BG\",\"RO\"].",
+          "items": {
+            "pattern": "^[A-Z]{2}$",
+            "type": "string"
+          },
+          "maxItems": 25,
+          "minItems": 1,
+          "type": "array"
+        },
+        "regions": {
+          "description": "Region location ids as [{key:\"...\"}], from Ads Manager targeting search.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "key": {
+                "pattern": "^\\d+$",
+                "type": "string"
+              }
+            },
+            "required": [
+              "key"
+            ],
+            "type": "object"
+          },
+          "maxItems": 200,
+          "type": "array"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}
  2. First observedv0.7.0

TDQS

A3.7/5.0
Behavior4/5

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses the dry-run-by-default behavior and the two accepted photo sources with where the bytes come from, which is genuinely useful for a write tool. It stops short of covering permission requirements, rate limits, or what a successful call returns.

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?

Two front-loaded sentences with no padding: purpose first, then photo-source constraints, then the dry-run default. Efficient, though it could have squeezed in the draft/scheduled parameter names it already mentions to tighten the link to the schema.

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

Completeness4/5

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

For an 11-parameter mutation tool with a nested targeting object and no output schema, the description covers the key decision points (photo source, dry run, draft vs publish, album). The remaining details (targeting, alt_text, page_timezone, plan_id) are fully documented in the schema, so nothing critical 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 schema already documents all 11 parameters in depth, including apply, plan_id, targeting, and scheduling rules. The description only restates the photo source and album routing, adding little beyond the structured fields; baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('Publish ONE photo to a Page') and the capitalized 'ONE' signals single-photo scope, which meaningfully separates it from the text, video, and story creation siblings. It never names those siblings explicitly, so the differentiation is inferred rather than stated.

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

Usage Guidelines3/5

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

The description covers the options (caption, draft, scheduled, album) and the important fact that it is a dry run by default, which implies when the tool is appropriate. However, it gives no explicit guidance on when to pick this over facebook_create_post, facebook_create_video_post, or facebook_create_story, leaving the alternative routing to inference.

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

Deploy Server

Other Tools