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

$3

``bash
npm install -g albi-mcp
`

$3

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

$3

Add this to your Claude Desktop config file:

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

`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.

$3

Completely quit and restart the Claude Desktop app.

$3

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:

$3

- "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"

$3

- "Create a new contact named John Smith with email john@example.com"
- "List all insurance adjuster contacts"
- "Show me contacts from State Farm"

$3

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

$3

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

$3

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

📊 Features

$3

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.

$3

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

$3

- ✅ 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

$3

Enable detailed logging to stderr:

`json
{
"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.

$3

For development or testing the latest changes:

`bash


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:

`json
{
"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:

$3


- health_check - Verify API connectivity and server status

$3

- 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

$3

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

$3

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

$3

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

$3

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

$3

- get_staff_member - Get staff member details

$3

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

$3

- 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

$3

- 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

$3

- 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

$3

Auto-rebuild on file changes:

`bash
npm run watch
`

$3

Compile TypeScript:

`bash
npm run build
`

$3

`
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

$3

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.

$3

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

$3

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

$3

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?"

$3

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.

$3

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

$3

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

$3

- ✅ 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

$3

- ✅ 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)

$3

- 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.