Context Portal MCP server for AI agents

ConPort is a database-backed Model Context Protocol (MCP) server that serves as a "memory bank" for your software projects. It stores structured project information like decisions, tasks, and architecture patterns, allowing AI assistants to understand your project better and provide more relevant responses.

What ConPort Does

ConPort creates a project-specific knowledge graph with:

Structured storage for project decisions, progress, and system designs
Custom project data management (glossaries, specifications)
Vector embeddings for semantic search capabilities
Retrieval Augmented Generation (RAG) support for AI assistants
SQLite database backend (one per workspace)

Prerequisites

Before installing ConPort, ensure you have:

Python: Version 3.8 or higher
uv: (Highly Recommended) A fast Python package manager

Installation with uvx (Recommended)

The easiest way to install and run ConPort is using uvx to execute the package directly from PyPI:

Configure in your MCP client settings

Add the following to your MCP client settings (e.g., mcp_settings.json):

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from",
        "context-portal-mcp",
        "conport-mcp",
        "--mode",
        "stdio",
        "--workspace_id",
        "${workspaceFolder}",
        "--log-file",
        "./logs/conport.log",
        "--log-level",
        "INFO"
      ]
    }
  }
}

Key parameters:

--workspace_id: The absolute path to your project (typically using the ${workspaceFolder} IDE variable)
--log-file: Optional path for server logs
--log-level: Sets logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Installation for Developers

If you want to work with the source code:

Clone the repository:

git clone https://github.com/GreatScottyMac/context-portal.git
cd context-portal

Create and activate a virtual environment:

uv venv
source .venv/bin/activate  # Linux/macOS
# Or for Windows: .venv\Scripts\activate.bat

Install dependencies:
```
uv pip install -r requirements.txt
```

Verify installation:

uv run python src/context_portal_mcp/main.py --help

Using ConPort with LLM Agents

To get the most out of ConPort, provide custom instructions to your LLM agents. ConPort includes ready-made strategy files for different environments:

For Roo Code: Use roo_code_conport_strategy
For CLine: Use cline_conport_strategy
For Windsurf Cascade: Use cascade_conport_strategy
For general use: Use generic_conport_strategy

To use these strategy files:

Copy the entire content of the appropriate file
Paste it into your LLM's custom instructions or system prompt area
Start your session with: Initialize according to custom instructions.

Setting Up a New Project

When using ConPort with a new project:

Create a Project Brief: Add a projectBrief.md file to your project root with:
- Project goals and purpose
- Key features/components
- Target audience
- Main architectural choices
- Other foundational information
Let the LLM Import It: When you start your LLM session, it will detect the file and offer to import it into ConPort's Product Context.

Available ConPort Tools

ConPort provides these MCP tools (all require workspace_id parameter):

Product Context Management

get_product_context: Retrieves project goals, features, and architecture
update_product_context: Updates product context

Active Context Management

get_active_context: Retrieves current focus, changes, and issues
update_active_context: Updates active context

Decision Logging

log_decision: Records project decisions
get_decisions: Retrieves logged decisions
search_decisions_fts: Full-text search across decisions
delete_decision_by_id: Removes a decision

Progress Tracking

log_progress: Records progress or task status
get_progress: Retrieves progress entries
update_progress: Updates progress entries
delete_progress_by_id: Removes a progress entry

System Pattern Management

log_system_pattern: Records coding patterns
get_system_patterns: Retrieves system patterns
delete_system_pattern_by_id: Removes a pattern

Custom Data Management

log_custom_data: Stores custom key-value data
get_custom_data: Retrieves custom data
delete_custom_data: Removes custom data
search_project_glossary_fts: Searches project glossary
search_custom_data_value_fts: Searches all custom data

Context Linking

link_conport_items: Creates relationships between items
get_linked_items: Retrieves linked items

History & Meta Tools

get_item_history: Retrieves version history
get_recent_activity_summary: Summarizes recent activity
get_conport_schema: Retrieves available tools schema

Import/Export

export_conport_to_markdown: Exports data to markdown
import_markdown_to_conport: Imports from markdown

Batch Operations

batch_log_items: Logs multiple items in a single call

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "conport" '{"command":"uvx","args":["--from","context-portal-mcp","conport-mcp","--mode","stdio","--workspace_id","${workspaceFolder}","--log-file","./logs/conport.log","--log-level","INFO"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "conport": {
            "command": "uvx",
            "args": [
                "--from",
                "context-portal-mcp",
                "conport-mcp",
                "--mode",
                "stdio",
                "--workspace_id",
                "${workspaceFolder}",
                "--log-file",
                "./logs/conport.log",
                "--log-level",
                "INFO"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "conport": {
            "command": "uvx",
            "args": [
                "--from",
                "context-portal-mcp",
                "conport-mcp",
                "--mode",
                "stdio",
                "--workspace_id",
                "${workspaceFolder}",
                "--log-file",
                "./logs/conport.log",
                "--log-level",
                "INFO"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect