What can you do with this server?

Florence-2 MCP Server provides local vision, OCR, and image/PDF analysis capabilities to MCP-compatible AI assistants. * Extract visible text with ocr from local files or HTTP/HTTPS URLs, including multi-page PDFs page-by-page. * Generate detailed image captions with caption. * Run custom Florence-2 task prompts with process, such as object detection, dense region captions, region proposals, and OCR with bounding boxes. * Process common image formats and PDF documents locally/offline, with automatic Apple Silicon, NVIDIA GPU, or CPU acceleration. * Return results as arrays of strings and optionally cache the model for faster repeated calls.

Which integrations are available for this server?

Hosts the repository for the Florence-2 MCP server, allows installation via git

How do I use Florence-2 MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Florence-2 MCP Server extract text from this screenshot of a document" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

Florence-2 MCP Server

by jkawamoto

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Florence-2 MCP Server

Python Version Python Application pre-commit GitHub License

Florence-2 MCP Server brings local vision intelligence and Optical Character Recognition (OCR) to your AI assistants via the Model Context Protocol (MCP). Powered by Microsoft's Florence-2 foundation model, it lets your LLMs inspect, caption, and extract text from local images, web URLs, and multi-page PDF documents — entirely offline and on your own machine.

✨ Key Features

🔒 100% Local & Private: All image and document processing runs on your local machine. No external vision API fees, token limits, or data sharing.
📄 Multi-Page PDF & Image Support: Process common image formats (JPEG, PNG, WebP, etc.) as well as multi-page PDF documents page-by-page.
⚡ Native Hardware Acceleration: Automatically detects and leverages Apple Silicon (MPS), NVIDIA GPU (CUDA), or CPU.
🧹 Zero VRAM Waste: By default, inference runs in an on-demand subprocess to release VRAM immediately after completion. A --cache-model flag is available for low-latency continuous usage.
🎯 Rich Vision Tasks: Perform high-precision text OCR, detailed descriptive captioning, and open-ended visual queries using native Florence-2 prompt tokens (e.g. object detection, region descriptions).
📦 One-Click Installs: Ready-to-use .mcpb bundle for Claude Desktop, 1-click deeplink for LM Studio, and extension support for Goose.

Related MCP server: 🪄 ImageSorcery MCP

🚀 Quick Installation

Choose your preferred MCP client below:

Claude Desktop

Option 1: One-Click Extension Bundle (Recommended)

Download the latest mcp-florence2.mcpb bundle from the Releases page.
Double-click the downloaded .mcpb file, or drag-and-drop it into Claude Desktop's Settings window.

Option 2: Manual Configuration

Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "florence-2": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jkawamoto/mcp-florence2",
        "mcp-florence2"
      ]
    }
  }
}

NOTE

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

For more details, see Connect to local MCP servers.

Goose

Option 1: One-Click URL

Click the link below to launch the Goose extension installer:

goose://extension?cmd=uvx&arg=--from&arg=git%2Bhttps%3A%2F%2Fgithub.com%2Fjkawamoto%2Fmcp-florence2&arg=mcp-florence2&id=florence2&name=Florence-2&description=An%20MCP%20server%20for%20processing%20images%20using%20Florence-2

Option 2: Manual Configuration

Add the following to ~/.config/goose/config.yaml:

extensions:
  florence2:
    name: Florence-2
    cmd: uvx
    args: [ --from, git+https://github.com/jkawamoto/mcp-florence2, mcp-florence2 ]
    enabled: true
    type: stdio

For more details, refer to Using Extensions | goose.

LM Studio

Click the button below to install directly into LM Studio:

Add MCP Server florence-2 to LM Studio

Claude Code, Cursor, Cline & Other MCP Clients

You can connect any client that supports stdio MCP servers using uvx:

uvx --from git+https://github.com/jkawamoto/mcp-florence2 mcp-florence2

🛠️ Tools

The server automatically equips your AI assistant with the following vision capabilities. You can interact with them using natural language:

1. `ocr`

Extracts all visible text from images or multi-page PDF documents.

Example user request: "Please extract all text from /path/to/invoice.pdf."
Multi-page support: Automatically iterates through every page in a PDF document.

Parameter	Type	Required	Description
`src`	`string`	Yes	Local file path or HTTP/HTTPS URL of an image or PDF file.

2. `caption`

Generates comprehensive, detailed captions describing what is depicted in the image.

Example user request: "Describe what is shown in https://example.com/photo.jpg."
Returns granular descriptions of objects, spatial relationships, colors, and background scenery.

Parameter	Type	Required	Description
`src`	`string`	Yes	Local file path or HTTP/HTTPS URL of an image or PDF file.

3. `process`

Executes custom Florence-2 task prompts directly against the input image or PDF for advanced computer vision workflows (such as object detection or region captioning).

Example user request: "Detect all objects in this image and return their bounding boxes."

Parameters

Parameter	Type	Required	Description
`src`	`string`	Yes	Local file path or HTTP/HTTPS URL of an image or PDF file.
`prompt`	`string`	Yes	Task prompt specifying the operation to perform.

Supported Florence-2 Task Prompts

Task Prompt	Description
`<CAPTION>`	Concise one-sentence summary of the image.
`<DETAILED_CAPTION>`	Moderate-length description of the image content.
`<MORE_DETAILED_CAPTION>`	Highly detailed and exhaustive scene description.
`<OCR>`	Plain text extraction from the image.
`<OCR_WITH_REGION>`	Text extraction along with bounding box coordinates.
`<OD>`	Object detection (identifies objects and their bounding boxes).
`<DENSE_REGION_CAPTION>`	Generates descriptions for multiple distinct regions.
`<REGION_PROPOSAL>`	Identifies candidate bounding boxes for prominent visual regions.

⚙️ Configuration & CLI Options

The server can be customized using command-line arguments:

mcp-florence2 [OPTIONS]

Option	Type	Default	Description
`--model`	`string`	`florence-community/Florence-2-large`	Hugging Face model identifier to load.
`--cache-model`	`flag`	`false`	Keeps the model in VRAM for faster repeated calls (by default, models run in subprocesses to free memory when idle).
`--version`	`flag`	-	Show version information.
`--help`	`flag`	-	Show help message and exit.

Using a Smaller / Faster Model

If you have limited GPU memory or want faster execution, switch to Florence-2-base:

{
  "mcpServers": {
    "florence-2": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jkawamoto/mcp-florence2",
        "mcp-florence2",
        "--model",
        "florence-community/Florence-2-base"
      ]
    }
  }
}

🛡️ Security Considerations

When processing URLs starting with http:// or https://, outbound HTTP requests are initiated directly from the server process. In environments where untrusted users or prompts may supply URLs, this could potentially expose the server to Server-Side Request Forgery (SSRF) targeting internal network services or cloud metadata endpoints.

WARNING

In multi-tenant or untrusted environments, route outgoing HTTP(S) traffic through an SSRF-safe forward proxy (such asSmokescreen or Squid configured to block private/internal IP ranges).

Since Python's requests library automatically respects standard environment variables, proxy settings can be configured directly in your client configuration:

HTTP_PROXY / http_proxy: Proxy URL for HTTP requests.
HTTPS_PROXY / https_proxy: Proxy URL for HTTPS requests.
NO_PROXY / no_proxy: Comma-separated list of hosts to bypass the proxy.

Claude Desktop

Add the env block to claude_desktop_config.json:

{
  "mcpServers": {
    "florence-2": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jkawamoto/mcp-florence2",
        "mcp-florence2"
      ],
      "env": {
        "HTTP_PROXY": "http://proxy.example.com:8080",
        "HTTPS_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}

Goose

Add the env block to ~/.config/goose/config.yaml:

extensions:
  florence2:
    name: Florence-2
    cmd: uvx
    args: [ --from, git+https://github.com/jkawamoto/mcp-florence2, mcp-florence2 ]
    env:
      HTTP_PROXY: "http://proxy.example.com:8080"
      HTTPS_PROXY: "http://proxy.example.com:8080"
    enabled: true
    type: stdio

💻 Development

Setup & Run Tests

This project uses uv for fast, reliable dependency management.

# Clone the repository
git clone https://github.com/jkawamoto/mcp-florence2.git
cd mcp-florence2

# Install dependencies and run tests
uv run pytest

# Run pre-commit checks
uv run pre-commit run --all-files

📄 License

This application is released under the MIT License.

Available Tools

3 tools

captionA

Processes an image file and generates captions for the image.

Name	Required	Description	Default
`src`	Yes	A file path or URL to the image file that needs to be processed.

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

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

Description discloses basic behavior (process image, generate caption) but lacks details on performance, file size limits, or output format. With no annotations, it carries full burden and does adequately for a simple tool.

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

Conciseness5/5

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

Single, clear sentence with no redundancy. Every word contributes meaning, and it is front-loaded with the core function.

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?

Given the tool's simplicity (one parameter, output schema exists), the description is complete enough for an agent to understand purpose. Slightly more context on output format would elevate to 5.

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 covers parameter 'src' with description 'A file path or URL to the image file'. The tool description adds no additional meaning beyond what the schema provides. Schema coverage is 100%, so baseline 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 uses a specific verb 'Processes' with a clear resource 'image file' and outcome 'generates captions'. It effectively distinguishes from the sibling tool 'ocr' which likely extracts text.

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?

No explicit guidance on when to use this tool vs alternatives. Usage is implied from context (generating captions vs OCR), but no exclusions or prerequisites are stated.

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

ocrB

Process an image file or URL using OCR to extract text.

Name	Required	Description	Default
`src`	Yes	A file path or URL to the image file that needs to be processed.

Output Schema

Name	Required	Description
`result`	Yes

TDQS

B3.4/5.0

Behavior2/5

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

No annotations provided. The description does not disclose side effects, required permissions, rate limits, or any behavioral traits beyond the basic action. It is too minimal for a tool without annotations.

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

Conciseness5/5

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

The description is a single sentence, front-loaded, with no unnecessary words. It efficiently conveys the core purpose.

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?

Given the tool's simplicity and presence of an output schema (not detailed here), the description covers the essential input and action. It could mention output format, but overall adequate for a straightforward OCR tool.

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% for the lone parameter, which already describes 'src' as a file path or URL. The tool description adds no extra meaning, so baseline 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 action (OCR) and the resource (image file or URL) and the output (extract text). It distinguishes from sibling tool 'caption' which likely does a different task.

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives. The description does not mention prerequisites, when not to use, or compare with sibling 'caption'.

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

processB

Processes an image file with a custom prompt using the Florence-2 model.

Name	Required	Description	Default
`src`	Yes	A file path or URL to the image file that needs to be processed.
`prompt`	Yes	A custom prompt for the Florence-2 model.

Output Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior2/5

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

No annotations are present, so the description must carry the full behavioral burden. It only says the tool 'processes' the image and names the model, but does not disclose side effects, failure modes, or notable runtime behavior. The term 'processes' is opaque and adds little transparency beyond the obvious operation.

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

Conciseness5/5

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

The description is a single, front-loaded sentence with no filler or repetition. Every word contributes to identifying what the tool does and with which model.

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

Completeness3/5

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

For a simple two-parameter tool with a full input schema and an output schema, this is minimally sufficient. The main missing piece is explicit usage guidance relative to the sibling tools, but the description does state the core action, target file, and model.

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 both parameters adequately. The description adds the model context ('Florence-2') and clarifies that the prompt is custom, but it does not significantly expand on the parameter meaning already present in the schema.

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?

The description states a specific action ('Processes an image file') and a resource plus tool ('custom prompt using the Florence-2 model'). It is not a tautology and gives enough context to understand the tool's basic role, though 'processes' is somewhat generic. The mention of a custom prompt weakly distinguishes it from the sibling tools 'caption' and 'ocr'.

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 phrase 'custom prompt' implies this tool is for flexible, user-defined vision tasks rather than the specialized sibling operations 'caption' and 'ocr'. However, the description never explicitly states when to prefer this tool over those alternatives, nor does it give exclusions or prerequisites.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

1 tool updatev0.5.0Sep 14, 2026
- Addedprocess

2 tool updatesv0.3.14Jun 18, 2026

Changedcaption1 field changed

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "items": {
+        "type": "string"
+      },
+      "title": "Result",
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "captionOutput",
+  "type": "object"
+}

Changedocr1 field changed

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "items": {
+        "type": "string"
+      },
+      "title": "Result",
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "ocrOutput",
+  "type": "object"
+}

2 tool updatesAug 21, 2025
- First observedcaption
- First observedocr

Deploy Server

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

TDQS

B3.4/5.0

Scored 2026-09-14 22:15 across 3 tools

Disambiguation3/5

The 'process' tool is generic and overlaps with 'caption', as captioning is a specific use case that could be handled by process. 'ocr' is distinct. The descriptions help clarify intended use, but the boundary between process and caption is not fully clear.

Naming Consistency4/5

All tools use a single lowercase verb (process, caption, ocr), which is consistent in style. However, the lack of noun objects (e.g., 'process_image' vs 'process') makes them slightly less predictable, but the pattern is uniform.

Tool Count4/5

With 3 tools, the server is on the lighter side but within a reasonable range for a focused vision model server. It covers the core capabilities without being bloated, though it could benefit from a few more specialized tools.

Completeness3/5

The tools cover generic processing, captioning, and OCR, but Florence-2 supports many other vision tasks (e.g., object detection, segmentation, grounding) that are not exposed. The generic 'process' tool mitigates some gaps, but the surface feels incomplete for the model's full potential.

Maintenance

ActivityMaintained

ResponsivenessSlow

Resources

Related MCP Connectors

mcp-qwen-image
io.github.AceDataCloud
MCP server for Qwen Image 3 AI image generation
AI & Machine Learning Image & Video Processing
1
https://qwen-image.mcp.acedata.cloud/mcp
mcp-flux-pro
io.github.AceDataCloud
MCP server for Flux AI image generation
Image & Video Processing Multimedia Processing
23
https://flux.mcp.acedata.cloud/mcp
mcp-wan
io.github.AceDataCloud
MCP server for Wan AI video generation
AI & Machine Learning Image & Video Processing
21
https://wan.mcp.acedata.cloud/mcp
mcp-grok
io.github.AceDataCloud
MCP server for Grok Imagine AI video generation
AI & Machine Learning Image & Video Processing
31
https://grok.mcp.acedata.cloud/mcp

Related MCP Servers

MCP Read Images
Image & Video Processing Autonomous Agents
catalystneuro
A
license
Not graded
quality
D
maintenance
An MCP server for analyzing images using OpenRouter vision models, offering capabilities like automatic image resizing, model configuration, and handling custom queries about images.
Updated 2 years ago (2025-01-26 21:51 UTC)
11
MIT
🪄 ImageSorcery MCP
Developer Tools Image & Video Processing
sunriseapps
A
license
Not graded
quality
F
maintenance
An MCP server providing tools for image processing operations
Updated 6 months ago (2026-05-19 08:19 UTC)
171 PyPI
335
Python
MIT
mcp-gemini-image
AI & Machine Learning Image & Video Processing
Earlybird-Technology
A
license
Not graded
quality
D
maintenance
An MCP server that provides image generation capabilities using Google's Gemini 2.5 Flash Image Preview model.
Updated a year ago (2025-09-30 11:52 UTC)
84 npm
MIT
api-draw
Image & Video Processing AI & Machine Learning
ruiyan-D
F
license
Not graded
quality
D
maintenance
MCP server for generating and editing images using gpt-image-2. Enables image creation, editing, listing, and retrieval via natural language tools.
Updated 3 months ago (2026-08-12 10:05 UTC)
-

Florence-2 MCP Server

✨ Key Features

🚀 Quick Installation

Claude Desktop

Option 1: One-Click Extension Bundle (Recommended)

Option 2: Manual Configuration

Goose

Option 1: One-Click URL

Option 2: Manual Configuration

LM Studio

Claude Code, Cursor, Cline & Other MCP Clients

🛠️ Tools

1. ocr

2. caption

3. process

Parameters

Supported Florence-2 Task Prompts

⚙️ Configuration & CLI Options

Using a Smaller / Faster Model

🛡️ Security Considerations

Claude Desktop

Goose

💻 Development

Setup & Run Tests

📄 License

Available Tools

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches

1. `ocr`

2. `caption`

3. `process`