papr-memory-mcp 0.1.2

Papr Memory API integration for MCP (Model Context Protocol) servers

Papr MCP Server

A FastAPI-based MCP (Memory Control Protocol) server implementation for integrating with Papr's memory services (https://papr.ai).

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Prerequisites

• Python 3.10 or higher
• Get your API key: You can find it in the settings section of papr.ai. You'll need to create a developer account on Papr to get your API key.

Quick Start

1. Clone this repository for Python MCP Papr Server:

git clone https://github.com/Papr-ai/papr_mcpserver
cd python-mcp

2. Run the setup script:

# Try python3 first (recommended for cross-platform compatibility)
python3 setup_run_mcp.py

# If python3 is not found, use python instead
python setup_run_mcp.py

Note: If python3 command is not found on your system, use python instead. This is common on Windows systems where Python 3 is installed as the default python command.

The setup script will guide you through the following steps:

1. Dependencies Installation

   • Installs uv if not already present
   • Creates a virtual environment (default '.venv')
   • Installs all required project dependencies

2. API Key Configuration

   • Prompts for your Papr API key
   • Validates the key format
   • Stores it securely in .env file

3. MCP Client Selection

   • Choose your preferred client:
     • Claude
     • Cursor AI
     • Other

4. Client Configuration

   • For Claude: Automatically configures claude_desktop_config.json
   • For Cursor AI: Automatically configures ./cursor/mcp.json
   • For Other clients: Displays the configuration JSON in console (you'll need to manually copy this to your client's configuration)

Note: If you select "Other" as your client, the script will print the MCP configuration JSON to the console. You'll need to manually copy this configuration to your client's appropriate configuration file.

The script will then:

• Start the MCP server (optional)

Tip: You can always start the server later using the options described in the "Manual Server Start" section below.

Setup Options

You can run the setup script with different options:

# Full setup with all prompts
python3 setup_run_mcp.py  # or python setup_run_mcp.py

# Skip dependency installation
python3 setup_run_mcp.py --skip-deps  # or python setup_run_mcp.py --skip-deps

# Skip setup and run server 
python3 setup_run_mcp.py --run-server  # or python setup_run_mcp.py --run-server

Start Server Directly

If you chose not to start the server during setup, you can start it manually:

On macOS/Linux:

# Using uv directly
source .venv/bin/activate
uv run python paprmcp.py

# For debugging run and use mcp inspector as client
source .venv/bin/activate
fastmcp dev paprmcp.py

On Windows:

# Using uv directly
.venv\Scripts\activate
uv run python paprmcp.py

# For debugging run and use mcp inspector as client
.venv\Scripts\activate
fastmcp dev paprmcp.py

On Windows PowerShell:

# Using uv directly
.venv\Scripts\Activate.ps1
uv run python paprmcp.py

# For debugging run and use mcp inspector as client
.venv\Scripts\Activate.ps1
fastmcp dev paprmcp.py

Note: Using the setup script with --run-server is recommended as it ensures the correct virtual environment is used and proper configuration is loaded.

Created Configuration

The setup script creates two main configuration files:

1. .env file in the project root:

   • Contains your Papr API key
   • Sets the memory server URL (default is memory.papr.ai)

2. MCP configuration file (location depends on your OS and chosen client):

   • macOS:
     • Claude: ~/Library/Application Support/claude/claude_desktop_config.json
     • Cursor: ./cursor/mcp.json
   • Windows:
     • Claude: %APPDATA%/claude/claude_desktop_config.json
     • Cursor: ./cursor/mcp.json
   • Linux:
     • Claude: ~/.config/claude/claude_desktop_config.json
     • Cursor: ./cursor/mcp.json

Development

The project uses pyproject.toml for dependency management with the following extras:

• dev: Development tools (debugpy, Flask, etc.)
• test: Testing tools (pytest, coverage, etc.)
• all: All of the above

To install specific extras:

uv pip install ".[dev]"  # Development dependencies
uv pip install ".[test]"  # Testing dependencies
uv pip install ".[all]"  # All dependencies

Debugging with VS Code

1. Install debugpy:

uv pip install ".[dev]" 

2. For MCP Inspector (optional): Install Node.js to get npx:

# On Windows (using winget)
winget install OpenJS.NodeJS
# After installation, refresh PATH in PowerShell:
$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH","User")

# Also ensure uv is properly installed and in PATH:
$env:PATH = "C:\Users\$env:USERNAME\.local\bin;$env:PATH"

# On macOS (using Homebrew)
brew install node

# On Linux (using package manager)
# Ubuntu/Debian:
sudo apt update && sudo apt install nodejs npm
# Or using NodeSource repository for latest version:
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

3. Start the server as well as mcp inspector in debug mode:

On macOS/Linux:

source .venv/bin/activate
python -m debugpy --wait-for-client --listen 5678 .venv/bin/fastmcp dev paprmcp.py

On Windows:

.venv\Scripts\activate
python -m debugpy --wait-for-client --listen 5678 .venv\Scripts\fastmcp.exe dev paprmcp.py

On Windows PowerShell:

.venv\Scripts\Activate.ps1
python -m debugpy --wait-for-client --listen 5678 .venv\Scripts\fastmcp.exe dev paprmcp.py

4. In VS Code:

   • Go to Run and Debug view (Ctrl+Shift+D or Cmd+Shift+D)
   • Select "Python: Attach to FastMCP"
   • Click the green play button or press F5
   • Set breakpoints in your code by clicking in the left margin
   • The debugger will stop at breakpoints when the code is executed

5. Using MCP Inspector (alternative to VS Code debugging):

   • After starting the server with fastmcp dev paprmcp.py, you can use the MCP inspector
   • The inspector will automatically connect to your running MCP server
   • This provides a web-based interface to test and interact with your MCP tools

Troubleshooting

If you encounter any issues:

1. Python command not found:

   • If python3 is not found, try using python instead
   • Check your Python installation: python --version or python3 --version
   • On Windows, Python 3 is often installed as python rather than python3

2. Windows-specific issues:

   • PowerShell execution policy: If you get execution policy errors, run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   • Virtual environment activation: Use .venv\Scripts\activate in Command Prompt or .venv\Scripts\Activate.ps1 in PowerShell
   • Path issues: Ensure uv is in your PATH. It's typically installed to %USERPROFILE%\.cargo\bin or %LOCALAPPDATA%\uv\bin

3. General issues:

   • Check the logs for detailed error messages
   • Ensure your Papr API key is correctly set in the .env file
   • Verify the virtual environment is activated
   • Make sure all dependencies are installed correctly

For additional help, please contact support or open an issue in the repository.