MCP Project Context Server

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

📖 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

About the Server
Prerequisites
Installation
Embedding Providers
- Ollama
- Voyage AI
- OpenAI
- Cohere
- Google Gemini
- Google Vertex AI
Vector Stores
Repository Providers
Transport
- stdio (Default)
- HTTP/SSE
Client Setup
Tools Reference
Environment Variables Reference
Project Structure
Testing
Roadmap
Contributing
License
Acknowledgments

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:

Sign up at voyageai.com
Navigate to Dashboard → API Keys
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:

Sign up or log in at platform.openai.com
Navigate to Dashboard → API Keys
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:

Sign up or log in at dashboard.cohere.com
Navigate to API Keys in the left sidebar
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:

Sign in at aistudio.google.com
Click Get API key in the top navigation
Click Create API key — choose an existing Google Cloud project or create a new one
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:

Enable the Vertex AI API in your Google Cloud project:
- Open console.cloud.google.com/apis/library
- Search for Vertex AI API and click Enable
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:

Go to github.com/settings/tokens
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
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:

Navigate to User Settings → Access Tokens (profile menu → Edit profile → Access Tokens)
Click Add new token
Grant at minimum the read_api scope
Set an expiry date and click Create personal access token
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:

Log in to your Gitea instance
Go to Settings → Applications (your user avatar → Settings → Applications)
Under Manage Access Tokens, enter a name, select the desired permissions, and click Generate Token
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

Install the server:

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

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

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"
      }
    }
  }
}

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

Claude Code

Install the server:

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

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"
      }
    }
  }
}

Verify the server is connected:
```
claude mcp list
```

Cursor

Install the server (see Installation)
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)

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"
      }
    }
  }
}

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

Continue

Install the Continue extension for VS Code or JetBrains
Locate the config file:

OS Config File

Windows %USERPROFILE%\.continue\config.yaml

macOS / Linux ~/.continue/config.yaml

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

Install the server (see Installation)
Locate the MCP config file:

OS Config File

Windows %USERPROFILE%\.codeium\windsurf\mcp_config.json

macOS / Linux ~/.codeium/windsurf/mcp_config.json

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"
      }
    }
  }
}

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.

Install the server (see Installation)

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"
        }
      }
    }
  }
}

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

Name		Name	Last commit message	Last commit date
.context		.context
.github		.github
.idea		.idea
docs		docs
scripts		scripts
src/mcp_project_context_server		src/mcp_project_context_server
tests		tests
.coveragerc.toml		.coveragerc.toml
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
pytest-example.md		pytest-example.md
qodana.yaml		qodana.yaml
requirements.txt		requirements.txt
tox.ini		tox.ini

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`

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

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

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

Latest commit

History

Folders and files

Repository files navigation

MCP Project Context Server

📖 About the Server

Core Capabilities

Key Features

📋 Table of Contents

Prerequisites

🚀 Installation

Core Package

Embedding Provider Extras

Vector Store Extras

HTTP/SSE Transport Extra

Combining Extras

Install Everything

From Source

🔌 Embedding Providers

Ollama

Voyage AI

OpenAI

Cohere

Google Gemini

Google Vertex AI

🗄️ Vector Stores

ChromaDB Local (Default)

ChromaDB HTTP

pgvector (PostgreSQL)

📁 Repository Providers

Local Filesystem (Default)

GitHub

GitLab

Gitea

Multi-Tenant Mode

🚌 Transport

stdio (Default)

HTTP/SSE

🖥️ Client Setup

Claude Desktop

Claude Code

Cursor

Continue

Windsurf

VS Code Copilot

🛠️ Tools Reference

Usage Examples

🌐 Environment Variables Reference

Embedding Providers

Vector Stores

Repository Providers

Transport

📂 Project Structure

🧪 Testing

Run the Test Suite

Development Workflow

🔮 Roadmap

🤝 Contributing

📝 License

🙏 Acknowledgments

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages