tribal_mcp_server

Tribal is an MCP server that stores, retrieves, and semantically searches error records to help developers learn from past mistakes. It exposes both a REST API via FastAPI and a native MCP interface so Claude Code and other MCP-enabled tools can interact with it. You can add, read, update, delete, and search error records, as well as perform semantic similarity searches to surface related issues and their solutions. The server uses ChromaDB for vector storage and supports JWT authentication with an API key for secure access. To get started, install the package, run the MCP server, and connect your MCP client or Claude integration to the configured MCP endpoint. The tooling includes a CLI client for common operations and a Claude integration workflow that can automatically register Tribal in Claude Code.

Prerequisites:

• Python 3.12+
• uv (Python package manager) available if you plan to install via uv as described in the project docs

Step 1: Install prerequisites and clone the repository

• Ensure Python is installed (version 3.12+ recommended)
• Clone the Tribal repository to a local directory

Step 2: Install Tribal (development or local installation) Option A: Direct installation cd /path/to/tribal uv pip install .

Option B: Development installation (editable) cd /path/to/tribal uv pip install -e .

Option C: Build and install a wheel cd /path/to/tribal uv pip install build python -m build uv pip install dist/tribal-0.1.0-py3-none-any.whl

Step 3: Run the MCP server

• You can run via the Python module interface: cd /path/to/tribal python -m mcp_server_tribal.mcp_app

• Or run the FastAPI server module (alternative entry): python -m mcp_server_tribal.app

Step 4: Verify the server is running

• Access the MCP endpoint (default port 5000)
• Access the FastAPI docs at http://localhost:8000/docs

Step 5: Configure Claude or MCP client

• Use the provided CLI or Claude integration steps from the README to add Tribal as an MCP source and verify connectivity.

Tips and caveats:

• Ensure environment variables are set for authentication and storage backends (e.g., API_KEY, MCP_API_URL, AWS_* for S3).
• The MCP server defaults: MCP_HOST=0.0.0.0, MCP_PORT=5000; FastAPI defaults: PORT=8000, API_KEY=dev-api-key, SECRET_KEY=insecure-dev-key-change-in-production.
• If using AWS S3, verify credentials and bucket permissions before starting the server.
• For local development, you can run the legacy MCP server or the modern Python module entry points; both expose the same MCP endpoints.
• When deploying with Docker or docker-compose, map ports consistently with MCP_PORT (5000) and FastAPI port (8000) and ensure environment variables are provided to the container.
• The environment supports vector search with ChromaDB; ensure storage path is writable (PERSIST_DIRECTORY for FastAPI).
• If you encounter port conflicts, use --port or MCP_PORT to choose a free port.