Text Classification MCP Server (Model2Vec)

A powerful Model Context Protocol (MCP) server that provides comprehensive text classification tools using fast static embeddings from Model2Vec (Minish Lab).

🛠️ Complete MCP Tools & Resources

This server provides 6 essential tools, 2 resources, and 1 prompt template for text classification:

🏷️ Classification Tools

• classify_text - Classify single text with confidence scores
• batch_classify - Classify multiple texts simultaneously

📝 Category Management Tools

• add_custom_category - Add individual custom categories
• batch_add_custom_categories - Add multiple categories at once
• list_categories - View all available categories
• remove_categories - Remove unwanted categories

📊 Resources

• categories://list - Access category list programmatically
• model://info - Get model and system information

💬 Prompt Templates

• classification_prompt - Ready-to-use classification prompt template

🚀 Key Features

• Zero-install: Just uv run — dependencies are declared inline (PEP 723)
• Multiple Transports: Supports stdio (local), HTTP/SSE, and Streamable HTTP
• Fast Classification: Uses efficient static embeddings from Model2Vec
• 10 Default Categories: Technology, business, health, sports, entertainment, politics, science, education, travel, food
• Custom Categories: Add your own categories with descriptions
• Batch Processing: Classify multiple texts at once
• Resource Endpoints: Access category lists and model information
• Prompt Templates: Built-in prompts for classification tasks

🛠️ Available Tools

classify_text

Classify a single text into predefined categories with confidence scores.

Parameters:

• text (string): The text to classify
• top_k (int, optional): Number of top categories to return (default: 3)

Returns: JSON with predictions, confidence scores, and category descriptions

Example:

classify_text("Apple announced new AI features", top_k=3)

batch_classify

Classify multiple texts simultaneously for efficient processing.

Parameters:

• texts (list): List of texts to classify
• top_k (int, optional): Number of top categories per text (default: 1)

Returns: JSON with batch classification results

Example:

batch_classify(["Tech news", "Sports update", "Business report"], top_k=2)

add_custom_category

Add a new custom category for classification.

Parameters:

• category_name (string): Name of the new category
• description (string): Description to generate the category embedding

Returns: JSON with operation result

Example:

add_custom_category("automotive", "Cars, vehicles, transportation, automotive industry")

batch_add_custom_categories

Add multiple custom categories in a single operation for efficiency.

Parameters:

• categories_data (list): List of dictionaries with 'name' and 'description' keys

Returns: JSON with batch operation results

Example:

batch_add_custom_categories([
    {"name": "automotive", "description": "Cars, vehicles, transportation"},
    {"name": "music", "description": "Music, songs, artists, albums, concerts"}
])

list_categories

List all available categories and their descriptions.

Parameters: None

Returns: JSON with all categories and their descriptions

remove_categories

Remove one or multiple categories from the classification system.

Parameters:

• category_names (list): List of category names to remove

Returns: JSON with removal results for each category

Example:

remove_categories(["automotive", "custom_category"])

📚 Available Resources

• categories://list: Get list of available categories with metadata
• model://info: Get information about the loaded Model2Vec model and system status

💬 Available Prompts

• classification_prompt: Template for text classification tasks with context and instructions

Parameters:

• text (string): The text to classify

Returns: Formatted prompt for classification with available categories listed

🧪 Testing

Test with MCP Inspector

npx @modelcontextprotocol/inspector uv run text_classifier_server.py

📖 Technical Details

• Model: minishlab/potion-base-8M from Model2Vec
• Similarity: Cosine similarity between text and category embeddings
• Performance: ~30MB model, fast inference with static embeddings
• Protocol: MCP specification 2024-11-05
• Transports: stdio, HTTP+SSE, Streamable HTTP

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Model2Vec by Minish Lab for fast static embeddings
• Anthropic for the Model Context Protocol specification
• FastMCP for the excellent Python MCP framework

Need help? Check the troubleshooting section or open an issue in the repository.

📋 Installation

Prerequisites

• Python 3.10+
• uv package manager

Quick Setup

No separate install step needed — dependencies are declared inline in the script (PEP 723) and resolved automatically by uv.

🏃‍♂️ Running the Server

Stdio Transport (Default)

uv run text_classifier_server.py

HTTP/SSE Transport

# SSE on default port 8000
uv run text_classifier_server.py --http

# SSE on custom port
uv run text_classifier_server.py --http 9000

Streamable HTTP Transport

uv run text_classifier_server.py --streamable-http

🔧 Configuration

For Claude Desktop

Stdio Transport (Local)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "text-classifier": {
      "command": "uv",
      "args": ["run", "/path/to/text_classifier_server.py"]
    }
  }
}

HTTP Transport (Remote)

Start the server with uv run text_classifier_server.py --http, then add:

{
  "mcpServers": {
    "text-classifier": {
      "url": "http://localhost:8000/sse"
    }
  }
}

For Claude Code

claude mcp add text-classifier -- uv run /Users/olivier/DEV/mcp-text-classifier/text_classifier_server.py

🔍 Troubleshooting

Model download fails

# Manual model download
uv run python -c "from model2vec import StaticModel; StaticModel.from_pretrained('minishlab/potion-base-8M')"