MCP Project Context Server

A Python MCP server that gives LLMs persistent, searchable access to project context — documentation, architecture decisions, and session notes.

License PyPI Python Version
Downloads Coverage Last Commit Issues

📖 About the Server

MCP Project Context Server provides a robust, production-ready Model Context Protocol (MCP) server implementation designed to give Large Language Models (LLMs) persistent, searchable access to your project's contextual information.

Core Capabilities

  • 🔍 Semantic Search Engine: Query your project documentation using natural language
  • 📚 Persistent Knowledge Base: Store and retrieve information from .context/ directory structure
  • 🏗️ Modular Architecture: Pluggable embedding providers, vector stores, and repository providers
  • 🎯 ADR Integration: Full support for Architecture Decision Records with lifecycle management
  • 📝 Session Tracking: Record and retrieve session notes for future reference
  • 🔄 Easy Reindexing: Rebuild your knowledge base with a single command

Key Features

  • ✅ Multi-Provider Embedding: Ollama, Voyage AI, OpenAI, Cohere, Google Gemini, and Google Vertex AI
  • ✅ Flexible Vector Storage: ChromaDB (local or HTTP) and pgvector (PostgreSQL)
  • ✅ Multiple Repository Providers: Local filesystem, GitHub, GitLab, and Gitea
  • ✅ Transport Options: stdio (default) and HTTP/SSE for remote deployments
  • ✅ Configuration-Free: Environment variable-based setup, no hardcoded paths
  • ✅ Cross-Platform: Works on Windows, macOS, and Linux
  • ✅ Async-First: All operations use async/await for performance and scalability
  • ✅ Error-Resilient: Graceful error handling with informative messaging

📋 Table of Contents

Prerequisites

Before installing, ensure you have:

  • Python 3.11+ installed
  • Ollama running with an embedding model (e.g., nomic-embed-text)
  • At least 2GB RAM available
  • 4.5GB disk space for ChromaDB (minimum)

🚀 Installation

Core Package

pip install mcp-project-context-server

The core package contains the server, tools, and ChromaDB local integration. It does not bundle any embedding provider SDK. You must install the extra for your chosen provider.

Embedding Provider Extras

Install the extra that matches your chosen embedding provider:

Provider Extra Install Command
Ollama (local, no API key) ollama pip install "mcp-project-context-server[ollama]"
Voyage AI voyage pip install "mcp-project-context-server[voyage]"
OpenAI openai pip install "mcp-project-context-server[openai]"
Cohere cohere pip install "mcp-project-context-server[cohere]"
Google Gemini google pip install "mcp-project-context-server[google]"
Google Vertex AI google-vertex pip install "mcp-project-context-server[google-vertex]"

Vector Store Extras

ChromaDB (local and HTTP) is included in the core package. Install the pgvector extra only if you are using PostgreSQL:

pip install "mcp-project-context-server[pgvector]"

HTTP/SSE Transport Extra

Required only when running the server over HTTP/SSE (remote deployments, Google Agent Engine, etc.):

pip install "mcp-project-context-server[sse]"

Combining Extras

Multiple extras can be combined in a single install:

# Ollama with pgvector
pip install "mcp-project-context-server[ollama,pgvector]"

# OpenAI with SSE transport
pip install "mcp-project-context-server[openai,sse]"

# Cohere with pgvector and SSE
pip install "mcp-project-context-server[cohere,pgvector,sse]"

Install Everything

pip install "mcp-project-context-server[all]"

From Source

git clone https://github.com/DarkMatterProductions/mcp-project-context-server.git
cd mcp-project-context-server
pip install -e ".[ollama]"  # Replace with your chosen provider extra

🔌 Embedding Providers

The embedding provider is selected by the EMBED_PROVIDER environment variable. This variable is required — the server will not start without it.

export EMBED_PROVIDER=ollama  # Replace with your chosen provider

Supported values: ollama, voyage, openai, cohere, google, vertexai

Ollama

Ollama runs embedding models locally. No API key is required.

Install:

pip install "mcp-project-context-server[ollama]"

Prerequisites: Install Ollama and pull an embedding model:

ollama pull nomic-embed-text

Environment Variables:

Variable Default Description
EMBED_PROVIDER — Must be set to ollama
OLLAMA_HOST http://localhost:11434 URL of the Ollama server
OLLAMA_EMBED_MODEL nomic-embed-text Embedding model to use

Example:

export EMBED_PROVIDER=ollama
export OLLAMA_HOST=http://localhost:11434    # Optional — this is the default
export OLLAMA_EMBED_MODEL=nomic-embed-text  # Optional — this is the default

Popular models:

Model Size Notes
nomic-embed-text ~274 MB Fast, good general purpose
mxbai-embed-large ~669 MB Higher quality
all-minilm ~46 MB Lightweight, lower quality

Voyage AI

Voyage AI provides embedding models optimized for code and technical content.

Install:

pip install "mcp-project-context-server[voyage]"

Getting an API Key:

  1. Sign up at voyageai.com
  2. Navigate to Dashboard → API Keys
  3. Click Create new key, give it a name, and copy the key value

Environment Variables:

Variable Default Description
EMBED_PROVIDER — Must be set to voyage
VOYAGE_API_KEY — Required. Your Voyage AI API key
VOYAGE_EMBED_MODEL voyage-code-3 Embedding model to use

Example:

export EMBED_PROVIDER=voyage
export VOYAGE_API_KEY=pa-...
export VOYAGE_EMBED_MODEL=voyage-code-3  # Optional

Recommended models:

Model Notes
voyage-code-3 Code-optimized, default
voyage-3 General purpose
voyage-3-lite Faster, lower cost

OpenAI

Install:

pip install "mcp-project-context-server[openai]"

Getting an API Key:

  1. Sign up or log in at platform.openai.com
  2. Navigate to Dashboard → API Keys
  3. Click Create new secret key, give it a name, and copy the key immediately — it is only shown once

Billing note: OpenAI API access is pay-per-use. Add a payment method at platform.openai.com/account/billing before your free credits run out.

Environment Variables:

Variable Default Description
EMBED_PROVIDER — Must be set to openai
OPENAI_API_KEY — Required. Your OpenAI API key
OPENAI_EMBED_MODEL text-embedding-3-small Embedding model to use

Example:

export EMBED_PROVIDER=openai
export OPENAI_API_KEY=sk-...
export OPENAI_EMBED_MODEL=text-embedding-3-small  # Optional

Recommended models:

Model Dimensions Notes
text-embedding-3-small 1536 Fast, cost-effective, default
text-embedding-3-large 3072 Highest quality

Cohere

Install:

pip install "mcp-project-context-server[cohere]"

Getting an API Key:

  1. Sign up or log in at dashboard.cohere.com
  2. Navigate to API Keys in the left sidebar
  3. Click New Trial Key (free tier, rate-limited) or New Production Key, then copy the value

Environment Variables:

Variable Default Description
EMBED_PROVIDER — Must be set to cohere
COHERE_API_KEY — Required. Your Cohere API key
COHERE_EMBED_MODEL embed-english-v3.0 Embedding model to use

Example:

export EMBED_PROVIDER=cohere
export COHERE_API_KEY=...
export COHERE_EMBED_MODEL=embed-english-v3.0  # Optional

Recommended models:

Model Notes
embed-english-v3.0 English, default
embed-multilingual-v3.0 100+ languages

Google Gemini

Uses the Google AI Studio API (Gemini embedding models).

Install:

pip install "mcp-project-context-server[google]"

Getting an API Key:

  1. Sign in at aistudio.google.com
  2. Click Get API key in the top navigation
  3. Click Create API key — choose an existing Google Cloud project or create a new one
  4. Copy the generated key

Note: Google AI Studio keys are suitable for development and personal use. For production workloads with higher quotas and enterprise SLAs, use Google Vertex AI instead.

Environment Variables:

Variable Default Description
EMBED_PROVIDER — Must be set to google
GOOGLE_API_KEY — Required. Your Google AI Studio API key
GOOGLE_EMBED_MODEL text-embedding-004 Embedding model to use

Example:

export EMBED_PROVIDER=google
export GOOGLE_API_KEY=AIza...
export GOOGLE_EMBED_MODEL=text-embedding-004  # Optional

Google Vertex AI

Uses the Vertex AI SDK with Google Cloud Application Default Credentials (ADC). No API key is required — authentication is handled through your Google Cloud identity.

Install:

pip install "mcp-project-context-server[google-vertex]"

Prerequisites:

  1. Enable the Vertex AI API in your Google Cloud project:

  2. Authenticate using Application Default Credentials. For local development:

    gcloud auth application-default login

    For production environments (e.g. Cloud Run, GKE), assign a service account with the Vertex AI User role (roles/aiplatform.user) to your workload, and set GOOGLE_APPLICATION_CREDENTIALS if using a key file.

Environment Variables:

Variable Default Description
EMBED_PROVIDER — Must be set to vertexai
VERTEXAI_PROJECT — Required. Your Google Cloud project ID
VERTEXAI_LOCATION — Required. Google Cloud region (e.g. us-central1)
VERTEXAI_EMBED_MODEL text-embedding-004 Embedding model to use

Example:

export EMBED_PROVIDER=vertexai
export VERTEXAI_PROJECT=my-gcp-project-id
export VERTEXAI_LOCATION=us-central1
export VERTEXAI_EMBED_MODEL=text-embedding-004  # Optional

🗄️ Vector Stores

The vector store is selected by the VECTOR_STORE_PROVIDER environment variable. Defaults to chroma-local.

Supported values: chroma-local, chroma-http, pgvector

ChromaDB Local (Default)

Persists embeddings in a local directory. Included in the core package — no extra installation required.

Environment Variables:

Variable Default Description
VECTOR_STORE_PROVIDER chroma-local Set to chroma-local or omit
CHROMA_DIR ~/.mcp-data/chroma Directory where ChromaDB stores its data

Example:

export VECTOR_STORE_PROVIDER=chroma-local  # Optional — this is the default
export CHROMA_DIR=~/.mcp-data/chroma       # Optional — this is the default

ChromaDB HTTP

Connects to a remote or containerized ChromaDB instance over HTTP.

Environment Variables:

Variable Default Description
VECTOR_STORE_PROVIDER chroma-local Must be set to chroma-http
CHROMA_HOST localhost ChromaDB server hostname
CHROMA_PORT 8000 ChromaDB server port
CHROMA_API_KEY (none) API key for ChromaDB Cloud or authenticated instances

Example:

export VECTOR_STORE_PROVIDER=chroma-http
export CHROMA_HOST=chroma.example.com
export CHROMA_PORT=8000
export CHROMA_API_KEY=your-chroma-api-key  # Optional

pgvector (PostgreSQL)

Stores embeddings in a PostgreSQL database using the pgvector extension.

Install:

pip install "mcp-project-context-server[pgvector]"

Prerequisites: A PostgreSQL instance (13+) with the pgvector extension enabled:

CREATE EXTENSION IF NOT EXISTS vector;

Environment Variables:

Variable Default Description
VECTOR_STORE_PROVIDER chroma-local Must be set to pgvector
PGVECTOR_CONNECTION_STRING — Required. PostgreSQL connection string

Example:

export VECTOR_STORE_PROVIDER=pgvector
export PGVECTOR_CONNECTION_STRING=postgresql://user:password@localhost:5432/mydb

📁 Repository Providers

The repository provider controls where the server reads project files from. Defaults to local.

Supported values: local, github, gitlab, gitea

Local Filesystem (Default)

Reads files from the local filesystem. No additional configuration required.

Environment Variables:

Variable Default Description
REPO_PROVIDER local Set to local or omit
PROJECT_PATH (from tool call) Override the project path at server startup

GitHub

Reads files from GitHub repositories via the GitHub REST API.

Getting a Personal Access Token:

  1. Go to github.com/settings/tokens
  2. Click Generate new token (classic) or Fine-grained personal access tokens
    • Classic: grant the repo scope (or public_repo for public repositories only)
    • Fine-grained: grant Contents: Read-only on the target repositories
  3. Copy the generated token

Environment Variables:

Variable Default Description
REPO_PROVIDER local Must be set to github
REPO_AUTH_TOKEN (empty) GitHub personal access token. Required for private repos
REPO_BASE_URL https://api.github.com Override for GitHub Enterprise Server
REPO_DEFAULT_BRANCH main Default branch when none is specified

Example:

export REPO_PROVIDER=github
export REPO_AUTH_TOKEN=ghp_...

# GitHub Enterprise only:
export REPO_BASE_URL=https://github.example.com/api/v3

GitLab

Reads files from GitLab repositories via the GitLab REST API.

Getting a Personal Access Token:

  1. Navigate to User Settings → Access Tokens (profile menu → Edit profile → Access Tokens)
  2. Click Add new token
  3. Grant at minimum the read_api scope
  4. Set an expiry date and click Create personal access token
  5. Copy the token immediately — it is not shown again

Environment Variables:

Variable Default Description
REPO_PROVIDER local Must be set to gitlab
REPO_AUTH_TOKEN (empty) GitLab personal access token
REPO_BASE_URL https://gitlab.com Override for self-hosted GitLab instances
REPO_DEFAULT_BRANCH main Default branch when none is specified

Example:

export REPO_PROVIDER=gitlab
export REPO_AUTH_TOKEN=glpat-...

# Self-hosted GitLab only:
export REPO_BASE_URL=https://gitlab.example.com

Gitea

Reads files from self-hosted Gitea instances. REPO_BASE_URL is required.

Getting an Access Token:

  1. Log in to your Gitea instance
  2. Go to Settings → Applications (your user avatar → Settings → Applications)
  3. Under Manage Access Tokens, enter a name, select the desired permissions, and click Generate Token
  4. Copy the generated token — it is only shown once

Environment Variables:

Variable Default Description
REPO_PROVIDER local Must be set to gitea
REPO_BASE_URL — Required. Your Gitea instance URL (e.g. https://gitea.example.com)
REPO_AUTH_TOKEN (empty) Gitea access token
REPO_DEFAULT_BRANCH main Default branch when none is specified

Example:

export REPO_PROVIDER=gitea
export REPO_BASE_URL=https://gitea.example.com
export REPO_AUTH_TOKEN=...

Multi-Tenant Mode

All repository providers support multi-tenant mode, which restricts file access to an allowlist of approved organizations and repositories. Enable it with REPO_MULTI_TENANT=true.

At least one of APPROVED_ORGS or APPROVED_REPOS must be set when multi-tenant mode is active.

Variable Default Description
REPO_MULTI_TENANT false Set to true to enable allowlist enforcement
APPROVED_ORGS (none) Comma-separated list of approved organization names
APPROVED_REPOS (none) Comma-separated list of approved owner/repo identifiers

Example:

export REPO_MULTI_TENANT=true
export APPROVED_ORGS=my-org,partner-org
export APPROVED_REPOS=other-org/specific-repo

🚌 Transport

The transport is selected by the MCP_TRANSPORT environment variable. Defaults to stdio.

stdio (Default)

Standard input/output transport. Compatible with Claude Desktop, Claude Code, Cursor, Continue, VS Code Copilot, and most other MCP clients. No additional installation or configuration required.

export MCP_TRANSPORT=stdio  # Optional — this is the default
project-context-server

HTTP/SSE

HTTP/SSE transport for remote deployments, team servers, and cloud integrations.

Install:

pip install "mcp-project-context-server[sse]"

Start the server:

export MCP_TRANSPORT=sse
export MCP_HOST=0.0.0.0  # Optional — default is 0.0.0.0
export MCP_PORT=8080      # Optional — default is 8080
project-context-server

The server exposes two endpoints:

  • GET /sse — SSE connection endpoint for MCP clients
  • GET /health — unauthenticated health check

Authentication:

MCP_AUTH_TYPE Description
none No authentication. Use only on trusted private networks.
bearer Static token via Authorization: Bearer <token>. Requires MCP_AUTH_TOKEN.
google-iam Google Cloud identity token validation. For use with Agent Engine and service-to-service calls.

Bearer token example:

export MCP_TRANSPORT=sse
export MCP_AUTH_TYPE=bearer
export MCP_AUTH_TOKEN=your-secret-token
project-context-server

Google IAM example:

export MCP_TRANSPORT=sse
export MCP_AUTH_TYPE=google-iam
export GOOGLE_IAM_AUDIENCE=https://my-service.example.com     # Recommended
export GOOGLE_APPROVED_SERVICE_ACCOUNTS=sa@project.iam.gserviceaccount.com  # Optional allowlist
project-context-server

SSE environment variables:

Variable Default Description
MCP_TRANSPORT stdio Must be set to sse
MCP_HOST 0.0.0.0 Bind address
MCP_PORT 8080 Listen port
MCP_AUTH_TYPE none Authentication: none, bearer, google-iam
MCP_AUTH_TOKEN — Required when MCP_AUTH_TYPE=bearer
GOOGLE_IAM_AUDIENCE (none) Expected aud claim in Google identity tokens
GOOGLE_SERVICE_ACCOUNT_KEY_PATH (none) Path to service account JSON key (uses ADC if unset)
GOOGLE_APPROVED_SERVICE_ACCOUNTS (none) Comma-separated allowed caller service account emails

🖥️ Client Setup

The examples below use Ollama as the embedding provider and ChromaDB local as the vector store — the simplest setup with no API key requirements. Substitute environment variables for your chosen providers using the reference in Embedding Providers and Vector Stores.

Detailed client docs with full per-provider configuration matrices are available in docs/clients/. Those docs are currently being updated to correct some environment variable names from the old implementation — see docs/client-setup-expansion.md for status and the correct variable reference.

Claude Desktop

  1. Install the server:

    pip install "mcp-project-context-server[ollama]"

  2. Locate the config file for your OS:

    OS Config File
    Windows %APPDATA%\Claude\claude_desktop_config.json
    macOS ~/Library/Application Support/Claude/claude_desktop_config.json
    Linux ~/.config/Claude/claude_desktop_config.json

  3. Add the server to claude_desktop_config.json:

    Windows:

    {
  "mcpServers": {
    "project-context": {
      "command": "python",
      "args": ["-m", "mcp_project_context_server"],
      "env": {
        "EMBED_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "nomic-embed-text"
      }
    }
  }
}

    macOS / Linux:

    {
  "mcpServers": {
    "project-context": {
      "command": "python",
      "args": ["-m", "mcp_project_context_server"],
      "env": {
        "EMBED_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "nomic-embed-text"
      }
    }
  }
}

  4. Restart Claude Desktop and verify the server appears in the MCP tools list.

Claude Code

  1. Install the server:

    pip install "mcp-project-context-server[ollama]"

  2. Add the MCP server using one of two methods:

    Option A — CLI:

    claude mcp add project-context \
  -e EMBED_PROVIDER=ollama \
  -e OLLAMA_HOST=http://localhost:11434 \
  -e OLLAMA_EMBED_MODEL=nomic-embed-text \
  -- python -m mcp_project_context_server

    Option B — Config file:

    Scope Location
    User (global) ~/.claude.json
    Project .claude/settings.json (in project root) 
    {
  "mcpServers": {
    "project-context": {
      "command": "python",
      "args": ["-m", "mcp_project_context_server"],
      "env": {
        "EMBED_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "nomic-embed-text"
      }
    }
  }
}

  3. Verify the server is connected:

    claude mcp list

Cursor

  1. Install the server (see Installation)

  2. Choose a config scope:

    Scope Windows macOS / Linux
    Global %USERPROFILE%\.cursor\mcp.json ~/.cursor/mcp.json
    Project .cursor\mcp.json (project root) .cursor/mcp.json (project root)

  3. Configure mcp.json:

    {
  "mcpServers": {
    "project-context": {
      "command": "python",
      "args": ["-m", "mcp_project_context_server"],
      "env": {
        "EMBED_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "nomic-embed-text"
      }
    }
  }
}

  4. Reload Cursor and use @project-context in the chat panel.

Continue

  1. Install the Continue extension for VS Code or JetBrains

  2. Locate the config file:

    OS Config File
    Windows %USERPROFILE%\.continue\config.yaml
    macOS / Linux ~/.continue/config.yaml

  3. Add to config.yaml:

    mcpServers:
  - name: project-context
    command: python
    args:
      - "-m"
      - mcp_project_context_server
    env:
      EMBED_PROVIDER: "ollama"
      OLLAMA_HOST: "http://localhost:11434"
      OLLAMA_EMBED_MODEL: "nomic-embed-text"

    Or if using config.json:

    {
  "mcpServers": [
    {
      "name": "project-context",
      "command": "python",
      "args": ["-m", "mcp_project_context_server"],
      "env": {
        "EMBED_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "nomic-embed-text"
      }
    }
  ]
}

Windsurf

  1. Install the server (see Installation)

  2. Locate the MCP config file:

    OS Config File
    Windows %USERPROFILE%\.codeium\windsurf\mcp_config.json
    macOS / Linux ~/.codeium/windsurf/mcp_config.json

  3. Configure mcp_config.json (create if it does not exist):

    {
  "mcpServers": {
    "project-context": {
      "command": "python",
      "args": ["-m", "mcp_project_context_server"],
      "env": {
        "EMBED_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "nomic-embed-text"
      }
    }
  }
}

  4. Restart Windsurf and verify the server appears under Settings → MCP Servers.

VS Code Copilot

MCP support is built into VS Code via GitHub Copilot (no separate extension required). Requires VS Code 1.99+ with the Copilot extension.

  1. Install the server (see Installation)

  2. Choose a config scope:

    Option A — Workspace (.vscode/mcp.json):

    {
  "servers": {
    "project-context": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mcp_project_context_server"],
      "env": {
        "EMBED_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "nomic-embed-text"
      }
    }
  }
}

    Option B — User settings (settings.json):

    {
  "mcp": {
    "servers": {
      "project-context": {
        "type": "stdio",
        "command": "python",
        "args": ["-m", "mcp_project_context_server"],
        "env": {
          "EMBED_PROVIDER": "ollama",
          "OLLAMA_HOST": "http://localhost:11434",
          "OLLAMA_EMBED_MODEL": "nomic-embed-text"
        }
      }
    }
  }
}

  3. Use in Copilot Chat by switching to Agent mode — MCP tools are available automatically.

🛠️ Tools Reference

Tool Description
index_project_context Indexes all files in .context/ into the configured vector store
search_project_context Performs semantic search over indexed context
load_project_context Returns the full contents of .context/ (project overview, ADRs, latest session)
save_session_summary Writes a session note to .context/sessions/YYYY-MM-DD.md
list_repositories Lists available repositories via the configured repository provider

Usage Examples

# Semantic search
search_project_context(
    query="How do we handle authentication?",
    n_results=5
)

# Load full context
load_project_context()
# Returns: project.md, all ADRs, latest session file

# Save session notes
save_session_summary(
    summary="Investigated chunking strategy alternatives, decided on fixed-size for now"
)

# Rebuild the index
index_project_context()

🌐 Environment Variables Reference

Embedding Providers

Variable Provider Default Required
EMBED_PROVIDER All — Yes
OLLAMA_HOST ollama http://localhost:11434 No
OLLAMA_EMBED_MODEL ollama nomic-embed-text No
VOYAGE_API_KEY voyage — Yes
VOYAGE_EMBED_MODEL voyage voyage-code-3 No
OPENAI_API_KEY openai — Yes
OPENAI_EMBED_MODEL openai text-embedding-3-small No
COHERE_API_KEY cohere — Yes
COHERE_EMBED_MODEL cohere embed-english-v3.0 No
GOOGLE_API_KEY google — Yes
GOOGLE_EMBED_MODEL google text-embedding-004 No
VERTEXAI_PROJECT vertexai — Yes
VERTEXAI_LOCATION vertexai — Yes
VERTEXAI_EMBED_MODEL vertexai text-embedding-004 No

Vector Stores

Variable Store Default Required
VECTOR_STORE_PROVIDER All chroma-local No
CHROMA_DIR chroma-local ~/.mcp-data/chroma No
CHROMA_HOST chroma-http localhost No
CHROMA_PORT chroma-http 8000 No
CHROMA_API_KEY chroma-http (none) No
PGVECTOR_CONNECTION_STRING pgvector — Yes (for pgvector)

Repository Providers

Variable Provider Default Required
REPO_PROVIDER All local No
PROJECT_PATH local (from tool call) No
REPO_AUTH_TOKEN github, gitlab, gitea (empty) No (required for private repos)
REPO_BASE_URL github, gitlab, gitea (provider default) Yes for gitea
REPO_DEFAULT_BRANCH github, gitlab, gitea main No
REPO_MULTI_TENANT All false No
APPROVED_ORGS All (multi-tenant) (none) Yes (if multi-tenant, with no APPROVED_REPOS)
APPROVED_REPOS All (multi-tenant) (none) Yes (if multi-tenant, with no APPROVED_ORGS)

Transport

Variable Default Required
MCP_TRANSPORT stdio No
MCP_HOST 0.0.0.0 No
MCP_PORT 8080 No
MCP_AUTH_TYPE none No
MCP_AUTH_TOKEN — Yes (if MCP_AUTH_TYPE=bearer)
GOOGLE_IAM_AUDIENCE (none) No
GOOGLE_SERVICE_ACCOUNT_KEY_PATH (none) No
GOOGLE_APPROVED_SERVICE_ACCOUNTS (none) No

📂 Project Structure

mcp-project-context-server/
├── src/mcp_project_context_server/
│   ├── server.py                       # MCP server entry point and tool registry
│   ├── exceptions.py                   # Shared exception types
│   ├── tools/
│   │   ├── index_context.py            # index_project_context tool
│   │   ├── search_context.py           # search_project_context tool
│   │   ├── load_context.py             # load_project_context tool
│   │   ├── save_session.py             # save_session_summary tool
│   │   └── list_repositories.py        # list_repositories tool
│   ├── integrations/
│   │   ├── embeddings/
│   │   │   ├── base.py                 # EmbeddingProvider Protocol
│   │   │   ├── registry.py             # Provider factory (EMBED_PROVIDER)
│   │   │   ├── ollama/client.py
│   │   │   ├── voyage/client.py
│   │   │   ├── openai/client.py
│   │   │   ├── cohere/client.py
│   │   │   ├── google/client.py
│   │   │   └── vertexai/client.py
│   │   ├── vectorstore/
│   │   │   ├── base.py                 # VectorStoreProvider Protocol
│   │   │   ├── registry.py             # Provider factory (VECTOR_STORE_PROVIDER)
│   │   │   ├── chroma_local/client.py
│   │   │   ├── chroma_http/client.py
│   │   │   └── pgvector/client.py
│   │   ├── repository/
│   │   │   ├── base.py                 # RepositoryProvider Protocol
│   │   │   ├── registry.py             # Provider factory (REPO_PROVIDER)
│   │   │   ├── local/client.py
│   │   │   ├── github/client.py
│   │   │   ├── gitlab/client.py
│   │   │   └── gitea/client.py
│   │   └── transport/
│   │       ├── stdio.py
│   │       └── sse.py
│   └── helpers/
│       └── context.py                  # Utility functions
├── .context/                            # Project context directory
│   ├── project.md                      # Project overview
│   ├── sessions/                       # Session notes
│   └── decisions/                      # Architecture Decision Records
├── tests/
│   ├── unit/                           # Unit tests (mocked dependencies)
│   └── integration/                    # Integration tests (real services)
├── docs/
│   └── client-setup-expansion.md       # Per-provider client setup expansion plan
├── README.md
├── CONTRIBUTING.md
├── pyproject.toml
└── LICENSE

🧪 Testing

Run the Test Suite

# Install test dependencies
pip install "mcp-project-context-server[all]"
pip install pytest pytest-asyncio pytest-mock pytest-cov

# Unit tests (no external services required)
pytest tests/unit/

# Integration tests (requires a running embedding provider and vector store)
pytest tests/integration/

# All tests with coverage report
pytest --cov=src/mcp_project_context_server tests/

Development Workflow

# Format and lint
black src/
isort src/
flake8 src/
mypy src/

# Check coverage
pytest --cov=src/mcp_project_context_server --cov-report=term-missing tests/unit/

🔮 Roadmap

  • Auto-reindex: Watchdog-based file monitoring for automatic reindexing
  • Codebase Indexing: Repomix integration for source code analysis
  • Enhanced ADR Tools: First-class MCP tools for ADR lifecycle management
  • Batch Operations: Bulk ADR updates and session imports
  • Provider Caching: Singleton caching for embedding and vector store providers

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for detailed guidelines including commit message standards, ADR requirements, and the PR process.

📝 License

This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3 — see the LICENSE file for details.

🙏 Acknowledgments

  • MCP Team: For the Model Context Protocol
  • ChromaDB: For the embedded vector store
  • Ollama: For local embedding model hosting

Built with ❤️ for better LLM project understanding

Project links

Data verified by PyPI on Sep 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ralnoc from gravatar.com ralnoc

Credits

Author: James Boylan

Maintainer: Darkmatter Productions

GitHub Statistics

Data verified by PyPI on Sep 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU Affero General Public License v3 (GNU AFFERO GENERAL PUBLIC LICENSE)

Requires

Python >=3.11

Provides Extra

ollama voyage openai cohere google google-vertex pgvector gcp-vector-search sse github gitlab gitea all

Tags

mcp model-context-protocol semantic-search chromadb llm documentation adr architecture-decision-records vector-store python server

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcp_project_context_server-1.0.0.tar.gz (110.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mcp_project_context_server-1.0.0-py3-none-any.whl (114.3 kB view details)

Uploaded Python 3

File details

Details for the file mcp_project_context_server-1.0.0.tar.gz.

File metadata

File hashes

Hashes for mcp_project_context_server-1.0.0.tar.gz
Algorithm Hash digest
SHA256 cf9ae08cfd5614d2ec77a7a7d1f6f14d3f5b14945ddf1842d3e95c7fc3f3fa3c
MD5 68cefe5ed92f3a85a628b3e59e1d02f4
BLAKE2b-256 560c36fc57d714577c7aded6a44da1456f86482777757be0e6c3ae8e6610d734

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcp_project_context_server-1.0.0.tar.gz:

Publisher: build-and-publish.yml on DarkMatterProductions/mcp-project-context-server

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mcp_project_context_server-1.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mcp_project_context_server-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c41659266c5eff1ea8120bc3770ebd4b509a04035939af9cf2c911bcf8e10fef
MD5 42c28b9b3a4f13f079601372efbf8835
BLAKE2b-256 6928fb8e3d99f463568b978302bafa320d492a0871e9f4f64d0b910d4bf05a2a

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcp_project_context_server-1.0.0-py3-none-any.whl:

Publisher: build-and-publish.yml on DarkMatterProductions/mcp-project-context-server

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 files

0.1.0

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page