Client Portal

npm version License: MIT Node.js

A lightweight Model Context Protocol (MCP) server for client relationship management (CRM). Perfect for freelancers, small businesses, and consultants who need simple yet effective client tracking.

🚀 Features

• 👥 Client Management - Add, update, and organize client information
• 🔍 Advanced Search - Find clients by name, company, email, or tags
• 📝 Notes & Interactions - Track meetings, calls, emails, and conversations
• 🏷️ Tagging System - Organize clients with custom tags
• 📊 Status Tracking - Monitor client status (active, prospect, churned)
• 💾 Local Storage - Simple JSON-based storage, no database required
• 🔒 Privacy-First - All data stays on your machine
• ⚡ Zero Configuration - Works out of the box

📦 Quick Start

Install and Run

# Install globally
npm install -g @artik0din/mcp-client-portal

# Or run directly with npx
npx @artik0din/mcp-client-portal

First Client

# Add your first client
add_client name="John Doe" email="[email protected]" company="Acme Corp" status="prospect" tags=["enterprise", "priority"]

# List all clients
list_clients

# Search for a client
search_clients query="john"

🛠️ MCP Client Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "client-portal": {
      "command": "npx",
      "args": ["@artik0din/mcp-client-portal"]
    }
  }
}

Other MCP Clients

The server communicates via stdio and follows the MCP protocol. Configure according to your client's requirements.

📋 Available Tools

👥 Client Management

Tool	Description	Parameters
add_client	Add new client	name, email, company?, phone?, address?, status?, tags?
list_clients	List all clients	status?, tag?, limit?
get_client	Get full client details	client_id
search_clients	Search clients	query
update_client	Update client info	client_id, name?, email?, company?, phone?, address?, status?, tags?

📝 Notes & Interactions

Tool	Description	Parameters
add_client_note	Add note or interaction	client_id, content, type?, subject?, date?, author?
list_client_interactions	List interaction history	client_id, type?, limit?

💡 Usage Examples

Client Management

# Add a new client
add_client name="Sarah Johnson" email="[email protected]" company="TechStart Inc" phone="+1-555-0123" status="active" tags=["startup", "tech"]

# List active clients only
list_clients status="active"

# List clients with a specific tag
list_clients tag="enterprise"

# Update client status
update_client client_id="123-abc" status="churned"

# Search clients by company
search_clients query="TechStart"

Notes & Interactions

# Add a simple note
add_client_note client_id="123-abc" content="Discussed Q4 requirements. Very interested in enterprise plan."

# Log a phone call
add_client_note client_id="123-abc" type="call" subject="Q4 Planning Call" content="45-minute call about scaling infrastructure. Next steps: send proposal by Friday." author="John Smith"

# Log an email interaction
add_client_note client_id="123-abc" type="email" subject="Proposal Follow-up" content="Sent detailed proposal. Waiting for feedback from technical team."

# Add a meeting with custom date
add_client_note client_id="123-abc" type="meeting" subject="Contract Negotiation" content="Discussed terms and pricing. Agreed on 10% discount for annual plan." date="2024-01-15T14:30:00Z"

# List all interactions for a client
list_client_interactions client_id="123-abc"

# List only phone calls
list_client_interactions client_id="123-abc" type="call"

Advanced Workflows

# Get complete client profile
get_client client_id="123-abc"

# Find all prospects that need follow-up
list_clients status="prospect"

# Track high-value clients
list_clients tag="enterprise"

# Search across all fields
search_clients query="startup"

🏷️ Client Status Types

Status	Description	Use Case
prospect	Potential client	Leads, initial contacts
active	Current client	Ongoing projects, contracts
inactive	Dormant client	Past clients, seasonal
churned	Lost client	Cancelled, competitors

📝 Interaction Types

Type	Description	Use Case
note	General note	Internal observations, reminders
email	Email exchange	Email conversations, proposals
call	Phone/video call	Sales calls, check-ins
meeting	In-person/online meeting	Presentations, negotiations
chat	Instant messaging	Quick questions, Slack/Teams
other	Custom interaction	Social media, events, other

💾 Data Storage

• Local Storage: Data stored in ~/.mcp-client-portal/clients.json
• JSON Format: Human-readable and easily portable
• No Database: Zero setup complexity
• Backup Ready: Simply copy the JSON file
• Privacy First: No cloud dependencies

Data Structure

{
  "id": "unique-client-id",
  "name": "Client Name",
  "company": "Company Inc",
  "email": "[email protected]",
  "phone": "+1-555-0123",
  "status": "active",
  "tags": ["enterprise", "priority"],
  "notes": [
    {
      "id": "note-id",
      "content": "Note content",
      "author": "Your Name",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "interactions": [
    {
      "id": "interaction-id",
      "type": "call",
      "subject": "Q4 Planning",
      "summary": "Discussed requirements...",
      "date": "2024-01-15T14:00:00Z",
      "createdAt": "2024-01-15T14:05:00Z"
    }
  ]
}

🔧 Migration & Integration

From Other CRMs

1. Export your data to CSV/JSON
2. Transform to match the client structure
3. Import by adding clients via the MCP tools
4. Bulk import scripts available in the repository

To Database Systems

When you outgrow JSON storage:

1. Export data: cp ~/.mcp-client-portal/clients.json backup.json
2. Transform data for your target database
3. Update storage.ts to use database instead of JSON
4. Maintains same MCP interface

🏗️ Development

# Clone and setup
git clone https://github.com/artik0din/mcp-client-portal.git
cd mcp-client-portal
npm install

# Development mode
npm run dev

# Build for production
npm run build

📄 License

MIT © 2026 Kevin Valfin

🤝 Contributing

Contributions welcome! Please read the contributing guidelines and submit PRs to the main branch.

Feature requests:

• Custom fields
• Email integration
• Calendar sync
• Export/import tools
• Dashboard views

🐛 Issues

Found a bug? Please file an issue on GitHub with:

• Node.js version
• Operating system
• Steps to reproduce
• Expected vs actual behavior

🔗 Links

• Model Context Protocol
• Claude Desktop
• MCP Servers Registry