Text Classification MCP Server (Model2Vec)

You can classify text using a dedicated MCP server that provides fast, context-aware embeddings from Model2Vec. It supports both local stdio and remote HTTP/SSE transports, lets you manage categories (including custom ones), and returns confidence scores to help you interpret results. This guide shows practical ways to run and use the server, configure clients, and perform common classification tasks.

How to use

Connect to the Text Classification MCP Server using your MCP client to perform single or batch classifications. You can classify texts locally in your IDE or script, or expose the server over HTTP for remote clients. Use the built‑in resources to inspect available categories and model information, and use the prompt templates to standardize classification prompts.

How to install

Prerequisites include Python 3.10 or newer and either uv (the MCP runner) or pip for dependency installation.

# Install dependencies
pip install -r requirements.txt

# Or install and run via uv if you use the MCP workflow
uv sync

Running the server locally (stdio) and remotely (HTTP)

Choose your transport based on how you want to consume the service. For local integration or development, run via stdio. For remote or multi-client access, run via HTTP with SSE.

# Run with stdio (local) using the default script
python text_classifier_server.py

# Or explicitly request stdio mode
python text_classifier_server.py --stdio

# Run with HTTP transport on localhost using default port 8000
python text_classifier_server.py --http

# Run on a custom port
python text_classifier_server.py --http 9000

# Alternatively, use a convenience script if provided
./start_server.sh http 8000

Using the HTTP runner

If you prefer an explicit HTTP runner, you can start the server with the HTTP transport and then connect your MCP client to the SSE endpoint.

# Example with explicit HTTP runner options
python run_http_server.py --transport http --host 127.0.0.1 --port 8000 --debug

Configuration and environment

Configure the server for your client environment as needed. The server supports both stdio and HTTP transports, and you can tailor how you start it depending on your workplace tooling.

Troubleshooting

If you run into issues, check server status, verify ports, and review logs for error details. Common checks include ensuring the chosen port is not in use and that the required Python version is installed.

# Check if a port is in use (example port 8000)
lsof -i :8000

# Start on a different port if needed
python text_classifier_server.py --http 9000

Notes and terminology

The server provides tools to classify text, manage categories, and query model information. You can classify a single string or batches of texts, and you can add or remove custom categories as your classification needs evolve.

Available tools

classify_text

Classify a single text into predefined categories with confidence scores.

batch_classify

Classify multiple texts simultaneously for efficient processing.

add_custom_category

Add a new custom category for classification.

batch_add_custom_categories

Add multiple custom categories in a single operation.

list_categories

List all available categories and their descriptions.

remove_categories

Remove one or multiple categories from the classification system.

categories://list

Access category list programmatically.

model://info

Get information about the loaded Model2Vec model and system status.

classification_prompt

Template for text classification tasks with context and instructions.