客户关系管理MCP服务器

一个通过 Model Context Protocol (MCP) 提供客户关系管理(CRM)能力的服务器,支持客户信息管理、搜索、交互记录与状态跟踪,适用于自由职业者、小企业和顾问。

  • by artik0din
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 globodai-group/mcp-client-portal

使用说明

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

  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