paperclip-mcp

April 7, 2026 · View on GitHub

MCP server for the Paperclip AI agent orchestration platform.

Exposes Paperclip's REST API as Model Context Protocol tools, so any MCP-compatible AI assistant (Claude, etc.) can manage issues, agents, goals, approvals, and costs through natural language.

Features

Category	Tools
Issues	`list_issues` · `get_issue` · `create_issue` · `update_issue` · `checkout_issue` · `release_issue` · `comment_on_issue` · `delete_issue`
Agents	`list_agents` · `get_agent` · `invoke_agent_heartbeat`
Goals	`list_goals` · `create_goal` · `update_goal`
Approvals	`list_approvals` · `approve` · `reject` · `request_approval_revision`
Monitoring	`get_cost_summary` · `get_dashboard` · `list_activity`

Requirements

Python 3.10+
A running Paperclip instance
An Agent API key (generated in Paperclip UI → Settings → API Keys)

Installation

Option A — pip / uv (recommended)

# Clone the repo
git clone https://github.com/wizarck/paperclip-mcp
cd paperclip-mcp

# Install (editable for local use, or drop -e for production)
pip install -e .
# or
uv pip install -e .

Option B — Run directly without installing

pip install fastmcp httpx python-dotenv
python src/paperclip_mcp/server.py

Configuration

Copy .env.example to .env and fill in your values:

cp .env.example .env

PAPERCLIP_BASE_URL=http://localhost:3100/api   # default, change if needed
PAPERCLIP_API_KEY=your_api_key_here
PAPERCLIP_COMPANY_ID=your_company_uuid_here

Security: Never commit .env to version control. It is listed in .gitignore.

Where to find these values:

PAPERCLIP_API_KEY — Paperclip UI → Settings → API Keys → New Key
PAPERCLIP_COMPANY_ID — visible in the URL when viewing your company: /companies/{uuid}

Usage

Start the server

# HTTP (for Claude Code / mcp-proxy) — default port 9011
paperclip-mcp

# Custom port
paperclip-mcp --port 9012

# stdio transport (for Claude Desktop)
paperclip-mcp --transport stdio

# All options
paperclip-mcp --help

Register with Claude Code

# HTTP transport (persistent — survives Claude restarts)
claude mcp add paperclip --transport http http://localhost:9011/mcp

# stdio transport (Claude Desktop — add to claude_desktop_config.json)

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "paperclip": {
      "command": "paperclip-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "PAPERCLIP_API_KEY": "your_api_key",
        "PAPERCLIP_COMPANY_ID": "your_company_uuid"
      }
    }
  }
}

Example interactions

Once registered, you can ask your AI assistant:

"What tasks does the Purchasing agent have open?"
→ calls list_issues(assignee_agent_id="...", status="todo,in_progress")

"Create a task for the CEO agent to search for new cheese suppliers in Barcelona"
→ calls create_issue(title="Search cheese suppliers in Barcelona", assignee_agent_id="...")

"Approve the pending hire request"
→ calls list_approvals(status="pending") + approve(approval_id="...")

"How much have we spent on tokens this month, broken down by agent?"
→ calls get_cost_summary()

"Wake up the Administration agent now"
→ calls invoke_agent_heartbeat(agent_id="...")

Auto-start with the MCP stack

Add to your stack startup script:

# Check if already running
curl -s --max-time 1 http://localhost:9011/mcp > /dev/null 2>&1 || \
  nohup paperclip-mcp > /tmp/paperclip-mcp.log 2>&1 &

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check src/
ruff format src/

# Type check
mypy src/

# Tests
pytest

Architecture notes

Who should use this MCP: Human operators managing agents via Claude Code or Claude Desktop.
Do agents need this MCP?: No — Paperclip agents already interact with the REST API directly via HTTP in their HEARTBEAT protocol. This MCP is for the human operator layer.
Hermes agents: If you switch to Hermes, this MCP is automatically available since Hermes supports MCP natively.
Transport choice: Use streamable-http for Claude Code and mcp-proxy integrations. Use stdio for Claude Desktop.
Security: The server binds to 127.0.0.1 by default (localhost only). Do not expose it publicly — it carries your Paperclip API key.

License

MIT — see LICENSE.