Clarifai/clarifai-mcp-server-local

Clarifai/clarifai-mcp-server-local

Description: Local MCP server for clarifai.com

Language: Go

Stars: 2

Forks: 2

Open issues: 0

Created: 2025-04-08T20:26:44Z

Pushed: 2025-05-14T09:39:22Z

Default branch: main

Fork: no

Archived: no

README:

🌀 Clarifai MCP Server (unofficial)

This hackday project provides a Model Context Protocol (MCP) server that acts as a bridge to the Clarifai API and is meant to run on user's machine (so locally). It allows MCP clients (like IDE extensions) to interact with Clarifai, such as image generation and inference, using standard MCP requests without overloading LLM context with heavy binary results.

 

Configuring MCP server for seamless interaction

The server is typically run automatically by the MCP client framework (e.g., via settings in VS Code). The configuration usually involves specifying the path to the built binary and any required command-line arguments, such as the Clarifai PAT. You will need Go (version 1.23 or later)

cd ~
git clone git@github.com:tot-ra/clarifai-mcp-server-local.git
cd clarifai-mcp-server-local
go mod tidy

Build the Binary: Use the go build command, targeting the main package within the cmd/server directory. Specify the output path and target architecture if needed (example for macOS ARM):

# For macOS ARM
make build

# For Linux AMD64
# GOOS=linux GOARCH=amd64 go build -o ./mcp_binary ./...

# For Windows AMD64
# GOOS=windows GOARCH=amd64 go build -o ./mcp_binary.exe ./...

This will create an executable file named mcp_binary (or mcp_binary.exe on Windows) in the project's root directory.

Example MCP settings entry (cline_mcp_settings.json), for example for Cline:

{
"mcpServers": {
"clarifai": {
"command": "~/clarifai-mcp-server-local/mcp_binary",
"args": [
"--pat", "YOUR_CLARIFAI_PAT",
"--output-path", "~/Desktop/",
"--default-user-id", "your_user_id",
"--default-app-id", "your_app_id",
],
}
}
}

Replace YOUR_CLARIFAI_PAT with your Clarifai PAT token.

Testing

Unit tests have been added for several packages. To run all tests, bypass the cache, and see verbose output (including individual test names and status):

cd clarifai-mcp-server-local
go test -v -count=1 ./...

Features

The server currently exposes the following MCP capabilities:

Tools

• `upload_file`: Uploads a local file to Clarifai as an input.
• Input: filepath (required, absolute path to the local file), user_id, app_id (optional).
• Output: Text confirmation and API response details upon successful upload.

• `generate_image`: Generates an image based on a text prompt using a specified or default Clarifai text-to-image model.
• Input: text_prompt (required), model_id, user_id, app_id (optional).
• Output: Base64 encoded image data (for small images) or a file path (for large images saved to the configured --output-path).

For example, given a user prompt, AI agent automatically can call image generation and places results on Desktop

> Generate 3 cat images with Clarifai

[](https://suno.com/song/3bd22d0f-3d88-4002-b1cc-ca3a3e14bf84?sh=XBiPBEm7hYz2FnBG)[](https://suno.com/song/d4f63bd4-a6cd-45f2-8bc1-0dea9ee7be01?sh=4UF4xlHkAkSbynRm)[](https://suno.com/song/1b9bef83-ed45-466a-b118-0c5481b2b6e9?sh=V0WDqyCzRGPCr4Vh)

• `clarifai_image_by_path`: Performs inference on a local image file using a specified or default Clarifai model.
• Input: filepath (required, path to the local image), model_id, user_id, app_id (optional).
• Output: Text description of inference results (e.g., concepts detected).

> Please clarifai images in my_source_folder/images/

• `clarifai_image_by_url`: Performs inference on an image URL using a specified or default Clarifai model.
• Input: image_url (required), model_id, user_id, app_id (optional).
• Output: Text description of inference results (e.g., concepts detected).

• `search_by_text`: Searches inputs based on a text query using Clarifai's PostInputSearches.
• Input: query (required, text query string), user_id, app_id, page, per_page (optional).
• Output: JSON string containing the search results (hits).

• `search_by_filepath`: Searches inputs based on similarity to a local image file using Clarifai's PostInputSearches.
• Input: filepath (required, absolute path to the local image file), user_id, app_id, page, per_page (optional).
• Output: JSON string containing the search results (hits).

• `search_by_url`: Searches inputs based on similarity to an image URL using Clarifai's PostInputSearches.
• Input: image_url (required, URL of the image), user_id, app_id, page, per_page (optional).
• Output: JSON string containing the search results (hits).

Resources (Read-Only)

The server exposes various Clarifai entities as read-only MCP resources, allowing clients to list, search, and read data using standard MCP methods (resources/list, resources/read). Actions like creating, updating, or deleting entities are handled via MCP Tools.

• Resource URI Scheme: Resources follow a consistent URI structure:

clarifai://{user_id}/{app_id}/{resource_type}[/{resource_id}][?query_params] Nested resources like model versions or dataset versions follow patterns like: clarifai://{user_id}/{app_id}/models/{model_id}/versions[/{version_id}] clarifai://{user_id}/{app_id}/datasets/{dataset_id}/versions[/{version_id}] clarifai://{user_id}/{app_id}/inputs/{input_id}/annotations

• Supported Resource Templates (`resources/templates/list`): The server provides templates for discovering available resources:
• Inputs: List, Search, Get
• clarifai://{user_id}/{app_id}/inputs
• clarifai://{user_id}/{app_id}/inputs?query={search_term}
• clarifai://{user_id}/{app_id}/inputs/{input_id}
• Annotations: List, Search, Get, List by Input
• clarifai://{user_id}/{app_id}/annotations
• clarifai://{user_id}/{app_id}/annotations?query={search_term}
• clarifai://{user_id}/{app_id}/annotations/{annotation_id}
• clarifai://{user_id}/{app_id}/inputs/{input_id}/annotations
• Models: List, Search, Get

*…