Mcp Florence2

io.github.jkawamotoPublished by GitHub account jkawamotov0.5.4Updated Nov 14, 2026

An MCP server for processing images using Florence-2

VerifiedSTDIODesktop onlyFiles & StorageMedia & Design

Overview

AI-generated overview

Runs Microsoft's Florence-2 vision model locally so an assistant can OCR, caption and run custom vision tasks on images and multi-page PDFs.

What you can do
  • Extract all visible text from images or multi-page PDFs, page by page
  • Generate detailed captions describing objects, layout, colors and background
  • Run custom Florence-2 task prompts such as object detection, region captions and bounding boxes
  • Accept either a local file path or an HTTP/HTTPS URL as the input source
When to use it
Useful when an assistant needs to read text from scanned documents, invoices or screenshots, or describe image content, without sending files to an external vision API. Suited to desktop setups with a GPU or Apple Silicon for faster inference.
Requirements
Runs as a local stdio process, typically launched with uvx or installed as an .mcpb bundle in Claude Desktop; desktop only. Downloads a Hugging Face Florence-2 model (large by default, base optional) and needs Python with uv, plus enough disk and memory or GPU; outbound HTTP access is needed only when processing URLs. Optional proxy settings via HTTP_PROXY, HTTPS_PROXY and NO_PROXY.
Before you install
Processing http or https URLs makes outbound requests from the server process, which the README warns can expose it to server-side request forgery against internal services or cloud metadata endpoints; use an SSRF-safe forward proxy in untrusted or multi-tenant settings. Files and URLs given to the tools are read by the local model, and the first run downloads model weights from Hugging Face.

Installation

In SourceWeft

  1. Open Mcp Florence2 in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

English | 日本語

Florence-2 MCP Server

[uv] [Python Version] [Python Application] [pre-commit] [GitHub License]

[MseeP.ai Security Assessment Badge]

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.

🚀 Quick Installation

Choose your preferred MCP client below:

Claude Desktop

Option 1: One-Click Extension Bundle (Recommended)
  1. Download the latest mcp-florence2.mcpb bundle from the Releases page.
  2. 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:

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:

text
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:

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:

bash
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.
Tool schema & parameters
ParameterTypeRequiredDescription
srcstringYesLocal 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.
Tool schema & parameters
ParameterTypeRequiredDescription
srcstringYesLocal 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."
Tool schema & supported task prompts
Parameters
ParameterTypeRequiredDescription
srcstringYesLocal file path or HTTP/HTTPS URL of an image or PDF file.
promptstringYesTask prompt specifying the operation to perform.
Supported Florence-2 Task Prompts
Task PromptDescription
<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:

bash
mcp-florence2 [OPTIONS]
OptionTypeDefaultDescription
--modelstringflorence-community/Florence-2-largeHugging Face model identifier to load.
--cache-modelflagfalseKeeps the model in VRAM for faster repeated calls (by default, models run in subprocesses to free memory when idle).
--versionflag-Show version information.
--helpflag-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:

json
{  "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 as Smokescreen 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.
Proxy Configuration Examples
Claude Desktop

Add the env block to claude_desktop_config.json:

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:

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.

bash
# Clone the repositorygit clone https://github.com/jkawamoto/mcp-florence2.gitcd mcp-florence2
# Install dependencies and run testsuv run pytest
# Run pre-commit checksuv run pre-commit run --all-files

📄 License

This application is released under the MIT License.

Source: README.md at commit 335b6df

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package type cannot run in the sandbox.

Version history

5
  1. v0.5.4LatestNov 14, 2026
  2. v0.5.3Oct 29, 2026
  3. v0.5.2Oct 21, 2026
  4. v0.5.1Oct 1, 2026
  5. v0.5.0Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts