Skip to main content
Glama
Sign In
enesjakozh

Chroma MCP Server

by privetin
GitHub
Python
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Servidor Chroma MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona funciones de búsqueda semántica y gestión de documentos mediante ChromaDB. Este servidor permite a los LLM realizar consultas en lenguaje natural sobre colecciones de documentos con métricas de similitud intuitivas, lo que lo hace ideal para aplicaciones RAG (Recuperación y Generación Aumentada).

Características

  • Búsqueda semántica : encuentre documentos según su significado utilizando incrustaciones de última generación
  • Métricas de similitud intuitivas : los resultados incluyen puntuaciones de similitud intuitivas (0-100 %)
  • Gestión documental : Operaciones CRUD completas para documentos y colecciones
  • Compatibilidad con metadatos enriquecidos : adjunte y busque por campos de metadatos personalizados
  • Almacenamiento persistente : almacenamiento confiable de documentos con backend SQLite
  • Seguridad : Controles de acceso configurables y validación de entrada
  • Manejo de errores : mensajes de error completos y recuperación de errores elegante

Requisitos

  • Python 3.12 o superior
  • ChromaDB 0.4.22 o superior
  • MCP Python SDK 1.1.2 o superior
  • Gestor de paquetes uv (recomendado) o pip

Inicio rápido

# Clone the repository git clone https://github.com/privetin/mcp-server-chroma.git cd mcp-server-chroma # Install with uv (recommended) uv venv .venv\Scripts\activate # Windows source .venv/bin/activate # Unix uv pip install -e . # Or with pip python -m venv .venv .venv\Scripts\activate # Windows source .venv/bin/activate # Unix pip install -e . # Run the server mcp-server-chroma

Para la integración de Claude Desktop, consulte Instalación .

Arquitectura

El servidor está construido sobre:

  • ChromaDB para almacenamiento y búsqueda de vectores
  • SDK de Python de MCP para implementación de servidor
  • SQLite para almacenamiento persistente

Flujo de datos

  1. Los documentos se incrustan utilizando el modelo de incrustación predeterminado de ChromaDB
  2. Las incrustaciones y los metadatos se almacenan en el backend SQLite de ChromaDB
  3. Las consultas se procesan a través del mismo modelo de incrustación.
  4. Los resultados se normalizan a una escala de similitud del 0 al 100 %.

Componentes

Colecciones y documentos

El servidor administra dos tipos principales de recursos:

  • Colecciones : contenedores para documentos relacionados con configuraciones de incrustación compartidas
  • Documentos : Contenido de texto con metadatos e incrustaciones generadas automáticamente

Herramientas

Gestión de cobros

  • list-collections : Lista todas las colecciones disponibles
  • create-collection : Crea una nueva colección con configuraciones opcionales
  • delete-collection : Eliminar una colección y sus documentos

Operaciones de documentos

  • add-document : Agrega un nuevo documento con contenido y metadatos
  • get-document : recupera un documento específico por ID
  • update-document : Modificar el contenido o los metadatos del documento
  • delete-document : Eliminar un documento de una colección
  • search-documents : Búsqueda semántica con puntuaciones de similitud normalizadas

Instalación

Prerrequisitos

  • Python 3.12+
  • Gestor de paquetes uv (recomendado) o pip

Configuración

  1. Clonar el repositorio:
git clone https://github.com/privetin/mcp-server-chroma.git cd mcp-server-chroma
  1. Crear y activar entorno virtual:
uv venv # On Windows: .venv\Scripts\activate # On Unix: source .venv/bin/activate
  1. Instalar dependencias:
uv pip install -e .

Integración de escritorio de Claude

Agregue el servidor a su configuración de Claude Desktop:

Ventanas ( %APPDATA%/Claude/claude_desktop_config.json ):

{ "mcpServers": { "chroma": { "command": "uv", "args": [ "--directory", "C:\\path\\to\\mcp-server-chroma", "run", "mcp-server-chroma" ] } } }

MacOS ( ~/Library/Application Support/Claude/claude_desktop_config.json ):

{ "mcpServers": { "chroma": { "command": "uv", "args": [ "--directory", "/path/to/mcp-server-chroma", "run", "mcp-server-chroma" ] } } }

Ejemplos de uso

Gestión de colecciones

Crear una colección:

Tool: create-collection Args: {"name": "research-papers"}

Lista de colecciones:

Tool: list-collections Args: {}

Trabajar con documentos

Agregar un documento:

Tool: add-document Args: { "collection": "research-papers", "content": "Recent advances in transformer architectures have led to significant improvements in natural language processing tasks.", "metadata": { "title": "Transformer Architectures", "year": 2024, "category": "ML" } }

Obtener un documento específico:

Tool: get-document Args: { "collection": "research-papers", "document_id": "doc_123" }

Actualizar un documento:

Tool: update-document Args: { "collection": "research-papers", "document_id": "doc_123", "content": "Updated findings on transformer architectures show improvements in both efficiency and accuracy.", "metadata": { "title": "Transformer Architectures - Updated", "year": 2024, "category": "ML", "status": "updated" } }

Buscar documentos:

Tool: search-documents Args: { "collection": "research-papers", "query": "What are the latest developments in transformers?", "n_results": 3 }

Comprensión de las puntuaciones de similitud

Los resultados de la búsqueda incluyen puntuaciones de similitud normalizadas del 0 al 100 %:

  • 90-100% : contenido casi idéntico o coincidencia semántica muy fuerte
  • 70-89% : Altamente relevante con fuerte similitud semántica
  • 50-69% : Moderadamente relacionado con superposición semántica parcial
  • 30-49% : Algo relacionado con una conexión semántica mínima
  • 0-29% : Probablemente no esté relacionado o tenga una conexión semántica muy débil

Solución de problemas

Problemas comunes

  1. Errores de conexión a la base de datos
    • Asegúrese de que la ruta de la base de datos sea escribible
    • Comprobar si otro proceso está utilizando la base de datos
    • Intente eliminar el directorio .chroma y reiniciar
  2. Problemas de memoria
    • Las colecciones grandes pueden requerir más RAM
    • Considere utilizar tamaños de lotes más pequeños
    • Supervisar el uso de memoria con --log-level DEBUG
  3. Rendimiento de búsqueda lento
    • Las colecciones grandes pueden necesitar optimización del índice
    • Considere usar menos n_results
    • Comprobar el uso de los recursos del sistema

Modo de depuración

Ejecute el servidor en modo de depuración:

mcp-server-chroma --log-level DEBUG

Obtener ayuda

Desarrollo

Ejecución de pruebas

Ejecute el conjunto de pruebas:

pytest -v

Correr con cobertura:

pytest --cov=chroma tests/

Depuración

Para la depuración, utilice el Inspector MCP:

# Install the inspector npm install -g @modelcontextprotocol/inspector # Run the server with inspector mcp-inspector uv --directory /path/to/mcp-server-chroma run mcp-server-chroma

El inspector proporciona:

  • Monitoreo de solicitudes y respuestas en tiempo real
  • Interfaz de prueba de herramientas
  • Métricas de rendimiento
  • Seguimiento de errores

Manejo de errores

El servidor proporciona mensajes de error detallados para escenarios comunes:

  • Nombres o identificaciones de colección no válidos
  • Documentos faltantes o malformados
  • Problemas de conexión a la base de datos
  • Parámetros de búsqueda no válidos
  • Fallos de autenticación/autorización

Consideraciones de seguridad

  • Validación de entrada en todos los parámetros
  • Controles de acceso configurables
  • Manejo seguro de rutas de archivos
  • Protección contra ataques de inyección
  • Soporte de limitación de velocidad
  • Mensajes de error seguros

Configuración

Ubicación de la base de datos

Establecer una ruta de base de datos personalizada:

mcp-server-chroma --db-path /path/to/db

Predeterminado: .chroma en el directorio del servidor

Variables de entorno

  • CHROMA_DB_PATH : Anular la ubicación de la base de datos
  • CHROMA_LOG_LEVEL : Establece el nivel de detalle del registro (predeterminado: INFO)
  • CHROMA_MAX_CONNECTIONS : Tamaño del grupo de conexiones de base de datos (predeterminado: 10)

Contribuyendo

  1. Bifurcar el repositorio
  2. Crear una rama de características
  3. Realiza tus cambios
  4. Agregar pruebas para nuevas funcionalidades
  5. Enviar una solicitud de extracción

Lea nuestras Pautas de contribución para obtener más detalles.

Licencia

Licencia MIT

Derechos de autor (c) 2024 privetin

Por la presente se concede permiso, sin cargo, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar el Software sin restricción, incluyendo, sin limitación, los derechos a usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir que las personas a quienes se les proporciona el Software lo hagan, sujeto a las siguientes condiciones:

El aviso de derechos de autor anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑOS U OTRAS RESPONSABILIDADES, YA SEA EN ACCIÓN CONTRACTUAL, EXTRACONTRACTUAL O DE OTRO TIPO, QUE SURJA DE, SE DERIVE DE O EN RELACIÓN CON EL SOFTWARE O EL USO U OTRAS RELACIONES CON EL MISMO.

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

Permite a los LLM realizar búsquedas semánticas y gestión de documentos utilizando ChromaDB, admitiendo consultas en lenguaje natural con métricas de similitud intuitivas para aplicaciones de generación aumentada de recuperación.

  1. Features
    1. Requirements
      1. Quick Start
        1. Architecture
          1. Data Flow
        2. Components
          1. Collections and Documents
          2. Tools
        3. Installation
          1. Prerequisites
          2. Setup
          3. Claude Desktop Integration
        4. Usage Examples
          1. Managing Collections
          2. Working with Documents
          3. Understanding Similarity Scores
        5. Troubleshooting
          1. Common Issues
          2. Debug Mode
          3. Getting Help
        6. Development
          1. Running Tests
          2. Debugging
          3. Error Handling
          4. Security Considerations
        7. Configuration
          1. Database Location
          2. Environment Variables
        8. Contributing
          1. License

            Related Resources

            Appeared in Searches

            ID: zcn8z6syk4