MCP Project Context Server

📖 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

Related MCP server: context-hub-mcp

📋 Table of Contents

• About the Server

• Prerequisites

• Installation

• 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

• 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:

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:

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:

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:

Example:

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

Recommended models:

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:

Example:

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

Recommended models:

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:

Example:

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

Recommended models:

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:

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:

   • Open console.cloud.google.com/apis/library

   • Search for Vertex AI API and click Enable

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:

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:

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:

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:

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:

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:

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:

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:

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.

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:

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:

🖥️ 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

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

Vector Stores

Repository Providers

Transport

📂 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