MCP 服务器

MCP Client Portal

A lightweight MCP server for client relationship management, enabling client tracking, notes, and search via natural language.

README

MCP Client Portal

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="john@example.com" 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="sarah@techstart.io" 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": "client@company.com",
  "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

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

To Database Systems

When you outgrow JSON storage:

Export data: cp ~/.mcp-client-portal/clients.json backup.json
Transform data for your target database
Update storage.ts to use database instead of JSON
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