Context Portal MCP server for AI agents

Context Portal (ConPort) is a database-backed Model Context Protocol (MCP) server that functions as your project's memory bank. It stores structured project context like decisions, tasks, and architectural patterns to help AI assistants provide more accurate and relevant responses to your project-specific queries.

What is ConPort?

ConPort stores and manages your project information in a structured database, making it easier for AI assistants to access and reference your project's specific details. It builds a project-specific knowledge graph that captures entities and their relationships, enhanced by vector embeddings for semantic search. This enables more intelligent, context-aware AI assistance through Retrieval Augmented Generation (RAG).

Prerequisites

Before installing ConPort, ensure you have:

Python: Version 3.8 or higher
uv: (Recommended) A fast Python environment and package manager that simplifies installation

Installation with uvx (Recommended)

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

Configuration in 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",
        "--log-file",
        "./logs/conport.log",
        "--log-level",
        "INFO"
      ]
    }
  }
}

Important Notes:

Many IDEs don't expand ${workspaceFolder} when launching MCP servers
You can either provide an absolute path for --workspace_id or omit it and rely on per-call workspace_id (recommended)
The --log-file path defines where server logs will be written
Set --log-level to DEBUG for more verbose output during troubleshooting

Automatic Workspace Detection

ConPort can automatically determine the correct workspace_id without requiring an absolute path in your configuration:

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from", "context-portal-mcp",
        "conport-mcp",
        "--mode", "stdio",
        "--log-level", "INFO"
      ]
    }
  }
}

To disable automatic detection and force using provided IDs only:

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from", "context-portal-mcp",
        "conport-mcp",
        "--mode", "stdio",
        "--no-auto-detect",
        "--workspace_id", "/absolute/path/to/project"
      ]
    }
  }
}

Usage with LLM Agents

ConPort works best when your LLM agent has specific instructions on how to use it. The repository includes tailored strategy files for different environments:

For Roo Code: roo_code_conport_strategy
For CLine: cline_conport_strategy
For Windsurf Cascade: cascade_conport_strategy
For General 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

When starting a new session, it's a good practice to tell the LLM:

Initialize according to custom instructions.

Initial Setup in a New Workspace

When first using ConPort in a project, consider creating a projectBrief.md file in your workspace root with an overview of your project. When an LLM agent initializes, it will detect this file and offer to import its content into ConPort's Product Context.

Available Tools

ConPort provides numerous tools for managing project context:

Product and Active Context

get_product_context: Retrieves overall project information
update_product_context: Updates the product context
get_active_context: Retrieves current working focus
update_active_context: Updates the active context

Decision Management

log_decision: Records architectural or implementation decisions
get_decisions: Retrieves logged decisions
search_decisions_fts: Full-text search across decisions
delete_decision_by_id: Removes a specific decision

Progress Tracking

log_progress: Records progress or task status
get_progress: Retrieves progress entries
update_progress: Updates an existing progress entry
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 entries
get_custom_data: Retrieves custom data
delete_custom_data: Removes custom data
search_project_glossary_fts: Searches within project glossary
search_custom_data_value_fts: Full-text search across all custom data

Context Linking and History

link_conport_items: Creates relationships between items
get_linked_items: Retrieves linked items
get_item_history: Shows version history
get_recent_activity_summary: Summarizes recent activity
get_conport_schema: Returns available tools and arguments

Import/Export and Batch Operations

export_conport_to_markdown: Exports data to markdown
import_markdown_to_conport: Imports from markdown
batch_log_items: Logs multiple items in one call

All tools require a workspace_id argument to specify the target project workspace.

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