Albi MCP Server

Model Context Protocol (MCP) server that connects Claude to the Albi API. This enables AI-powered interactions with your restoration project management data - query projects, manage contacts, create tasks, analyze financials, and more through natural language.

🚀 Quick Start

1. Install

npm install -g albi-mcp

2. Get Your API Key

1. Log into Albi
2. Navigate to Settings → API Keys
3. Generate or copy your API key (UUID format)

3. Configure Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "albi": {
      "command": "albi-mcp",
      "env": {
        "ALBI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Replace your-api-key-here with your actual Albi API key.

4. Restart Claude Desktop

Completely quit and restart the Claude Desktop app.

5. Test It

Ask Claude: "Can you check if the Albi API is connected?"

✅ You should see a successful health check response!

💡 What You Can Do

Once configured, you can use natural language to interact with your Albi workspace:

Project Management

• "Show me all active projects"
• "What's the financial status of project 1234?"
• "List all projects with negative margins"
• "Get the timeline for the Oak Brook water mitigation job"

Contact Management

• "Create a new contact named John Smith with email [email protected]"
• "List all insurance adjuster contacts"
• "Show me contacts from State Farm"

Financial Analysis

• "What's our total revenue pipeline this month?"
• "Show me aged receivables over 60 days"
• "Calculate average profit margin by project type"

Task & Activity Tracking

• "Create a task to follow up with the customer"
• "Show all activities for project 5678"
• "List overdue tasks"

Team Management

• "How many projects is Mary managing?"
• "Show staff workload distribution"
• "Who is assigned to the Chicago projects?"

📊 Features

Architecture Overview

26 consolidated tool definitions organized in 8 categories:

• Health Check (1 tool)
• Projects (11 tools)
• CRUD Operations (4 tools: contacts, organizations, tasks, activities)
• Staff (1 tool)
• Scheduler (2 tools)
• Options/Lookups (1 unified tool)
• Batch Operations (5 tools)
• Smart Search (1 unified tool)

Note: Claude Code UI displays these as 48 tools because it expands enum-based operations. For example, the contacts tool has 4 operations (list, get, create, update_status) which appear as 4 separate tools in the UI. This is expected behavior.

Core Capabilities

Projects (11 tools)

• Retrieve all projects or specific project details
• Access financials, payments, invoices, and expenses
• View project timeline, files, staff assignments, and notes
• Create project notes

Contacts & Organizations (2 consolidated tools with 4 operations each)

• List and retrieve contacts and organizations
• Create new contacts and organizations with full details
• Update contact and organization statuses
• Filter by relationship types and status

Tasks (1 consolidated tool with 4 operations)

• Get all tasks or specific task details
• Create new tasks with assignments and due dates
• Update task statuses

Activities (1 consolidated tool with 3 operations)

• List and retrieve activities
• Create new activities linked to contacts/organizations
• Track customer interactions

Staff & Scheduler (3 tools)

• Get staff member information and assignments
• Get and create scheduled events
• Create calendar entries for site visits and meetings

Options/Lookups (1 unified tool - cached for performance)

• 6 option types: project roles, relationship types, referral sources, activity types, relationship statuses, salesperson options
• All cached for 1 hour to reduce API calls

Batch Operations (5 tools for parallel execution)

• Batch create tasks, contacts, activities, and notes
• Batch update task statuses
• Execute multiple operations efficiently

Smart Search (1 unified tool)

• Search across projects, contacts, organizations, tasks
• Find contacts by email
• Paginated search up to 2,000 items (20 pages × 100 items)
• Searches: name, firstName, lastName, email, phone, company fields
• Case-insensitive matching

Technical Features

• ✅ Full CRUD Support: Create, read, update operations for all major entities
• ⚡ Smart Caching: Lookup endpoints cached for 1 hour
• 🔒 Input Validation: Zod schemas ensure data integrity
• 📦 Response Management: Automatic truncation of large responses (100KB limit)
• 🔍 Enhanced Error Handling: Clear, actionable error messages with context
• 📈 Pagination Support: Handle large datasets efficiently with auto-pagination
• 🔄 Batch Operations: Parallel execution for multiple operations
• 🔎 Unified Search: Single tool for all entity searches with pagination
• 🐛 Debug Mode: Detailed logging with ALBI_DEBUG=true
• 🎯 Token Optimized: Phase 2 consolidation reduced from 48 individual tools to 26 definitions (43% reduction)

🔧 Advanced Configuration

Debug Mode

Enable detailed logging to stderr:

{
  "mcpServers": {
    "albi": {
      "command": "albi-mcp",
      "env": {
        "ALBI_API_KEY": "your-api-key-here",
        "ALBI_DEBUG": "true"
      }
    }
  }
}

This logs all API calls, cache hits/misses, and tool executions with timestamps.

Install from Source

For development or testing the latest changes:

# Clone the repository
git clone https://github.com/thetenzinwoser-albi/albi-mcp.git
cd albi-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Link globally (makes 'albi-mcp' command available)
npm link

Then configure Claude Desktop with the same config as above, or use the dist path:

{
  "mcpServers": {
    "albi": {
      "command": "node",
      "args": ["/absolute/path/to/albi-mcp/dist/index.js"],
      "env": {
        "ALBI_API_KEY": "your-api-key-here"
      }
    }
  }
}

📚 Available Tools

The server exposes 26 consolidated tool definitions (displayed as 48 in Claude Code UI) covering all major Albi API endpoints:

Health & Connectivity (1 tool)

• health_check - Verify API connectivity and server status

Projects (11 tools)

• get_projects - List all projects with pagination
• get_project - Get detailed project information
• get_project_financials - Retrieve financial KPIs
• get_project_payments - List payment history
• get_project_invoices - Get invoice records
• get_project_expenses - View project expenses
• get_project_timeline - Access event history
• get_project_files - List uploaded documents
• get_project_staff - View team assignments
• get_project_notes - Read project notes
• create_note - Add notes to projects

Contacts (1 consolidated tool with 4 operations)

• contacts - Manage contacts with operations:
  • list - List all contacts
  • get - Get specific contact details
  • create - Create new contact
  • update_status - Modify contact status

Organizations (1 consolidated tool with 4 operations)

• organizations - Manage organizations with operations:
  • list - List all organizations
  • get - Get specific organization
  • create - Create new organization
  • update_status - Modify organization status

Tasks (1 consolidated tool with 4 operations)

• tasks - Manage tasks with operations:
  • list - List all tasks
  • get - Get specific task details
  • create - Create new task
  • update_status - Update task status

Activities (1 consolidated tool with 3 operations)

• activities - Manage activities with operations:
  • list - List all activities
  • get - Get specific activity
  • create - Create new activity

Staff (1 tool)

• get_staff_member - Get staff member details

Scheduler (2 tools)

• get_scheduled_events - List scheduled events
• create_scheduled_event - Create new calendar event

Options/Lookups (1 unified tool - cached)

• get_options - Get lookup options by type:
  • project_role - Available project roles
  • relationship_type - Relationship type dropdown
  • referral_source - Referral source options
  • activity_type - Activity type options
  • relationship_status - Status options
  • salesperson - Sales team members
  • All responses cached for 1 hour

Batch Operations (5 tools)

• batch_create_tasks - Create multiple tasks in parallel
• batch_create_contacts - Create multiple contacts in parallel
• batch_update_task_status - Update multiple task statuses
• batch_create_activities - Create multiple activities in parallel
• batch_create_notes - Add notes to multiple projects

Smart Search (1 unified tool)

• search - Search across entity types:
  • projects - Search projects by name/address
  • contacts - Search contacts by name/email/phone
  • organizations - Search organizations by company name
  • tasks - Search tasks
  • contact_by_email - Find specific contact by email
  • Searches up to 2,000 items (20 pages)
  • Case-insensitive matching

🛠️ Development

Watch Mode

Auto-rebuild on file changes:

npm run watch

Build

Compile TypeScript:

npm run build

Project Structure

albi-mcp/
├── src/
│   ├── index.ts          # MCP server and tool definitions
│   ├── albi-client.ts    # Albi API client wrapper
│   ├── types.ts          # TypeScript interfaces and Zod schemas
│   └── utils.ts          # Helper functions (logging, formatting, validation)
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── README.md
├── CLAUDE.md            # Project context for Claude Code
└── REAL_WORKFLOW_EXAMPLE.md  # Real-world usage examples

📖 Documentation

• API Reference: Albi API Docs
• MCP Protocol: Model Context Protocol
• Real Examples: See REAL_WORKFLOW_EXAMPLE.md
• Architecture: See CLAUDE.md

🐛 Troubleshooting

"Repository not found" or authentication errors

The MCP server doesn't need git access - only npm and Node.js. If you see git errors during installation, they can be safely ignored.

"Cannot find module" errors

Make sure you've run npm run build before using the server.

"Invalid API key" errors

Verify your API key:

1. Check it's a valid UUID format
2. Confirm it's active in your Albi account
3. Make sure there are no extra spaces in the config file

Tools not showing up in Claude

1. Completely quit Claude Desktop (not just close the window)
2. Restart the app
3. Check the config file syntax is valid JSON
4. Try asking: "What MCP servers are connected?"

Seeing 48 tools instead of 26?

This is expected behavior in Claude Code. The 26 tool definitions contain enum-based operations that expand in the UI:

• contacts tool → displays as 4 tools (list, get, create, update_status)
• organizations tool → displays as 4 tools
• tasks tool → displays as 4 tools
• activities tool → displays as 3 tools
• get_options tool → displays as 6 tools (one for each option type)
• search tool → displays as 5 tools (one for each entity type)

Token usage: The ~27,186 tokens reported is accurate - it includes the full JSON schemas with all enum values and property descriptions. This is the actual cost of loading the MCP server.

Response size errors

Some endpoints (like get_activities) can return very large responses. The server automatically truncates responses over 100KB and provides pagination metadata.

Search returning fewer results than expected?

The search tool has a pagination limit of 2,000 items (20 pages × 100 items per page). If your database contains more matching records, you may need to use more specific search terms or use the direct list endpoints with custom pagination.

🔒 Security

• API keys are stored in environment variables, never in code
• All API requests use HTTPS
• No data is persisted by the MCP server
• Input validation prevents injection attacks
• Rate limiting respects Albi API limits

📦 Version History

1.0.15 (Current)

• ✅ Documentation Update: Comprehensive README and CLAUDE.md updates
  • Clarified tool count display (26 definitions → 48 in Claude Code UI)
  • Added detailed troubleshooting for tool count questions
  • Enhanced search limitations documentation
  • Added testing & usage examples
  • Updated all tool descriptions to reflect consolidated architecture

1.0.14

• ✅ Phase 2 Token Optimization: Consolidated 48 individual tools → 26 definitions (43% reduction)
  • CRUD operations: 15 tools → 4 consolidated tools (contacts, organizations, tasks, activities)
  • Options/lookups: 6 tools → 1 unified tool with operation parameter
  • Search: 5 tools → 1 unified tool with entity type parameter
• ✅ Enhanced Search: Paginated search up to 2,000 items (20 pages × 100 items)
  • Searches: name, firstName, lastName, email, phone, company fields
  • Case-insensitive matching across all entity types
• ✅ Batch Operations: 5 new tools for parallel execution
  • Batch create: tasks, contacts, activities, notes
  • Batch update: task statuses
• ✅ Token Usage: ~27,186 tokens (includes full JSON schemas)
• ✅ Tool display: 26 definitions expand to 48 in Claude Code UI (expected behavior)

1.0.7-1.0.13

• Fixed all create endpoints to use correct /Create suffix
• Full CRUD support for contacts, organizations, tasks, activities
• Comprehensive error handling and validation
• Published to npm as albi-mcp
• Added input validation with Zod schemas
• Enhanced error messages with context
• Response size management (100KB limit)
• Caching for lookup endpoints (1 hour TTL)

🤝 Contributing

Contributions are welcome! This is an open-source project.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details

🔗 Links

• npm Package: https://www.npmjs.com/package/albi-mcp
• GitHub Repository: https://github.com/thetenzinwoser-albi/albi-mcp
• Albi Website: https://albiware.com
• Albi API Docs: https://albi.readme.io/reference

Made with ❤️ for the restoration industry

Connect your AI assistant to your project management data and unlock new insights.