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```bash
Install globally
npm install -g @artik0din/mcp-client-portal
Or run directly with npx
npx @artik0din/mcp-client-portal
### First Client```bash
# 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:```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```bash
# 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```bash
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```bash
# 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```json
{
"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```bash
# 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
