attio-mcp 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +8 -1
- package/README.md +190 -58
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.1.1] - 2025-01-06
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
- Fixed npm installation failing due to postinstall script trying to setup git hooks in non-git environments
|
|
14
|
+
- Postinstall script now only runs git hooks setup when .git directory exists
|
|
15
|
+
|
|
10
16
|
### Changed
|
|
11
17
|
- Updated LICENSE from BSD-3-Clause to Apache-2.0 while preserving original BSD license attribution
|
|
12
18
|
- Updated package.json author field to @kesslerio
|
|
@@ -58,5 +64,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
58
64
|
- Troubleshooting guides
|
|
59
65
|
- Development and contribution guidelines
|
|
60
66
|
|
|
61
|
-
[Unreleased]: https://github.com/kesslerio/attio-mcp-server/compare/v0.1.
|
|
67
|
+
[Unreleased]: https://github.com/kesslerio/attio-mcp-server/compare/v0.1.1...HEAD
|
|
68
|
+
[0.1.1]: https://github.com/kesslerio/attio-mcp-server/compare/v0.1.0...v0.1.1
|
|
62
69
|
[0.1.0]: https://github.com/kesslerio/attio-mcp-server/releases/tag/v0.1.0
|
package/README.md
CHANGED
|
@@ -1,105 +1,237 @@
|
|
|
1
1
|
# Attio MCP Server
|
|
2
2
|
|
|
3
|
-
[](https://codecov.io/gh/kesslerio/attio-mcp-server)
|
|
3
|
+
[](LICENSE)
|
|
4
|
+
[](https://badge.fury.io/js/attio-mcp)
|
|
6
5
|
[](https://nodejs.org/)
|
|
7
|
-
[](https://github.com/kesslerio/attio-mcp-server/releases)
|
|
8
7
|
|
|
9
|
-
A Model Context Protocol (MCP) server for [Attio](https://attio.com/), the AI-native CRM. This server enables AI assistants like Claude to interact directly with your Attio data, providing
|
|
8
|
+
A comprehensive Model Context Protocol (MCP) server for [Attio](https://attio.com/), the AI-native CRM. This server enables AI assistants like Claude to interact directly with your Attio data through natural language, providing seamless integration between conversational AI and your CRM workflows.
|
|
10
9
|
|
|
11
|
-
##
|
|
10
|
+
## 🎯 What is Attio MCP Server?
|
|
12
11
|
|
|
13
|
-
-
|
|
14
|
-
- Companies: Search, view details, manage notes
|
|
15
|
-
- People: Search (with email/phone support), view details, manage notes
|
|
16
|
-
- Lists: View, manage entries, add/remove records
|
|
17
|
-
- Records: Create, read, update, delete (coming soon)
|
|
18
|
-
- Tasks: Create, update, and link to records
|
|
12
|
+
Transform your CRM workflows with AI-powered automation. Instead of clicking through multiple screens, simply ask Claude to find prospects, update records, manage pipelines, and analyze your data using natural language commands.
|
|
19
13
|
|
|
20
|
-
|
|
21
|
-
- Robust error handling with helpful messages
|
|
22
|
-
- Automatic retry logic with exponential backoff
|
|
23
|
-
- Input validation to prevent common errors
|
|
24
|
-
- Standardized response formatting
|
|
14
|
+
> "Find all AI companies with 50+ employees that we haven't contacted in 30 days and add them to our Q1 outreach list"
|
|
25
15
|
|
|
26
|
-
##
|
|
16
|
+
## ✨ Core Features
|
|
27
17
|
|
|
28
|
-
|
|
18
|
+
### 📊 **Company Management** (27 Tools)
|
|
19
|
+
- **Smart Search**: Find companies by domain, text, or complex filters
|
|
20
|
+
- **Full CRUD**: Create, read, update, and delete company records
|
|
21
|
+
- **Relationship Discovery**: Find companies through their people's attributes
|
|
22
|
+
- **Batch Operations**: Process hundreds of companies efficiently
|
|
23
|
+
- **Notes & Activities**: Track all company interactions
|
|
29
24
|
|
|
25
|
+
### 👥 **People Management** (15 Tools)
|
|
26
|
+
- **Contact Search**: Find people by email, phone, name, or activity history
|
|
27
|
+
- **Relationship Tracking**: Link people to companies with role management
|
|
28
|
+
- **Activity Timeline**: Track all interactions and touchpoints
|
|
29
|
+
- **Advanced Filtering**: Multi-attribute search with date ranges
|
|
30
|
+
- **Bulk Operations**: Efficiently manage large contact databases
|
|
31
|
+
|
|
32
|
+
### 📋 **Lists & Pipeline Management** (11 Tools)
|
|
33
|
+
- **Pipeline Operations**: Move deals through sales stages
|
|
34
|
+
- **Smart Segmentation**: Create and manage targeted contact lists
|
|
35
|
+
- **Advanced Filtering**: Complex multi-condition filtering with AND/OR logic
|
|
36
|
+
- **Entry Management**: Add, remove, and update list memberships
|
|
37
|
+
- **Deal Tracking**: Monitor opportunities and revenue pipeline
|
|
38
|
+
|
|
39
|
+
### ✅ **Task Management** (5 Tools)
|
|
40
|
+
- **Assignment System**: Create and assign tasks to team members
|
|
41
|
+
- **Record Linking**: Associate tasks with CRM records
|
|
42
|
+
- **Progress Tracking**: Monitor completion and deadlines
|
|
43
|
+
- **Team Coordination**: Streamline follow-ups and activities
|
|
44
|
+
|
|
45
|
+
### 🔧 **Advanced Capabilities**
|
|
46
|
+
- **Batch Processing**: Handle bulk operations with error tracking
|
|
47
|
+
- **Flexible Filtering**: Text, numeric, date, boolean, and relationship filters
|
|
48
|
+
- **Data Export**: JSON serialization for integrations
|
|
49
|
+
- **Real-time Updates**: Live data synchronization with Attio
|
|
50
|
+
|
|
51
|
+
## 🚀 Installation
|
|
52
|
+
|
|
53
|
+
### Option 1: NPM (Recommended)
|
|
54
|
+
```bash
|
|
55
|
+
# Global installation for CLI usage
|
|
56
|
+
npm install -g attio-mcp
|
|
57
|
+
|
|
58
|
+
# Or local installation for project integration
|
|
59
|
+
npm install attio-mcp
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Option 2: One-Command Script Installation
|
|
63
|
+
```bash
|
|
64
|
+
curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/install.sh | bash
|
|
30
65
|
```
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
66
|
+
|
|
67
|
+
### Option 3: Manual Installation
|
|
68
|
+
```bash
|
|
69
|
+
git clone https://github.com/kesslerio/attio-mcp-server.git
|
|
70
|
+
cd attio-mcp-server
|
|
71
|
+
npm install
|
|
72
|
+
npm run build
|
|
35
73
|
```
|
|
36
74
|
|
|
37
75
|
## ⚡ Quick Start
|
|
38
76
|
|
|
39
77
|
### Prerequisites
|
|
40
|
-
|
|
41
78
|
- Node.js (v18 or higher)
|
|
42
|
-
- Attio API Key ([Get one here](https://
|
|
79
|
+
- Attio API Key ([Get one here](https://app.attio.com/settings/api))
|
|
80
|
+
- Attio Workspace ID
|
|
43
81
|
|
|
44
|
-
###
|
|
82
|
+
### 1. Set Environment Variables
|
|
83
|
+
```bash
|
|
84
|
+
export ATTIO_API_KEY="your_api_key_here"
|
|
85
|
+
export ATTIO_WORKSPACE_ID="your_workspace_id_here"
|
|
86
|
+
```
|
|
45
87
|
|
|
88
|
+
### 2. Test the Installation
|
|
46
89
|
```bash
|
|
47
|
-
|
|
90
|
+
# Test the MCP server
|
|
91
|
+
attio-mcp --help
|
|
92
|
+
|
|
93
|
+
# Discover your Attio workspace attributes
|
|
94
|
+
attio-discover attributes
|
|
48
95
|
```
|
|
49
96
|
|
|
50
|
-
###
|
|
97
|
+
### 3. Configure Claude Desktop
|
|
98
|
+
|
|
99
|
+
Add to your Claude Desktop MCP configuration:
|
|
51
100
|
|
|
52
101
|
```json
|
|
53
102
|
{
|
|
54
103
|
"mcpServers": {
|
|
55
|
-
"attio": {
|
|
56
|
-
"command": "
|
|
57
|
-
"args": ["attio-mcp-server"],
|
|
104
|
+
"attio-mcp": {
|
|
105
|
+
"command": "attio-mcp",
|
|
58
106
|
"env": {
|
|
59
|
-
"ATTIO_API_KEY": "
|
|
107
|
+
"ATTIO_API_KEY": "your_api_key_here",
|
|
108
|
+
"ATTIO_WORKSPACE_ID": "your_workspace_id_here"
|
|
60
109
|
}
|
|
61
110
|
}
|
|
62
111
|
}
|
|
63
112
|
}
|
|
64
113
|
```
|
|
65
114
|
|
|
66
|
-
##
|
|
115
|
+
## 🌟 Example Use Cases
|
|
116
|
+
|
|
117
|
+
### **For Sales Teams**
|
|
118
|
+
```
|
|
119
|
+
"Find all companies in the AI space with 50+ employees that we haven't contacted in 30 days"
|
|
120
|
+
"Create a task to follow up with Microsoft about the enterprise deal"
|
|
121
|
+
"Add John Smith from Google to our Q1 prospect list"
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### **For Marketing Teams**
|
|
125
|
+
```
|
|
126
|
+
"Create a list of all SaaS companies who opened our last 3 emails but haven't responded"
|
|
127
|
+
"Show me engagement metrics for our outbound campaign this month"
|
|
128
|
+
"Add all attendees from the conference to our nurture sequence"
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### **For Customer Success**
|
|
132
|
+
```
|
|
133
|
+
"Show me all enterprise customers with upcoming renewal dates in Q1"
|
|
134
|
+
"Create tasks for check-ins with accounts that haven't been contacted in 60 days"
|
|
135
|
+
"Find all customers who mentioned pricing concerns in recent notes"
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### **For Data Operations**
|
|
139
|
+
```
|
|
140
|
+
"Update all companies with missing industry data based on their domains"
|
|
141
|
+
"Export all contacts added this quarter to CSV"
|
|
142
|
+
"Merge duplicate company records for Acme Corporation"
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## 🔐 Security & Privacy
|
|
67
146
|
|
|
68
|
-
- **
|
|
69
|
-
- **
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
- Configurable through environment variables
|
|
147
|
+
- **Secure API Authentication**: Industry-standard API key authentication
|
|
148
|
+
- **No Data Storage**: Direct API passthrough with no local data retention
|
|
149
|
+
- **Open Source**: Full transparency with Apache 2.0 license
|
|
150
|
+
- **Optional On-Premises**: Deploy in your own infrastructure
|
|
73
151
|
|
|
74
152
|
## 📚 Documentation
|
|
75
153
|
|
|
76
|
-
|
|
154
|
+
Comprehensive documentation is available in the [docs directory](./docs):
|
|
77
155
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
156
|
+
### **Getting Started**
|
|
157
|
+
- [Installation & Setup](./docs/getting-started.md)
|
|
158
|
+
- [Claude Desktop Configuration](./docs/claude-desktop-config.md)
|
|
159
|
+
- [Troubleshooting Guide](./TROUBLESHOOTING.md)
|
|
82
160
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
161
|
+
### **API Reference**
|
|
162
|
+
- [API Overview](./docs/api/api-overview.md)
|
|
163
|
+
- [Companies API](./docs/api/companies-api.md)
|
|
164
|
+
- [People API](./docs/api/people-api.md)
|
|
165
|
+
- [Lists API](./docs/api/lists-api.md)
|
|
166
|
+
- [Notes API](./docs/api/notes-api.md)
|
|
167
|
+
- [Tasks API](./docs/api/tasks-api.md)
|
|
89
168
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
169
|
+
### **Advanced Topics**
|
|
170
|
+
- [Batch Operations](./docs/api/batch-operations.md)
|
|
171
|
+
- [Advanced Filtering](./docs/api/advanced-filtering.md)
|
|
172
|
+
- [Error Handling](./docs/api/error-handling.md)
|
|
173
|
+
- [Extending MCP](./docs/api/extending-mcp.md)
|
|
93
174
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
175
|
+
### **Deployment**
|
|
176
|
+
- [Docker Guide](./docs/docker/docker-guide.md)
|
|
177
|
+
- [Security Best Practices](./docs/docker/security-guide.md)
|
|
178
|
+
|
|
179
|
+
## 🛠 Development
|
|
180
|
+
|
|
181
|
+
### **Setup Development Environment**
|
|
182
|
+
```bash
|
|
183
|
+
git clone https://github.com/kesslerio/attio-mcp-server.git
|
|
184
|
+
cd attio-mcp-server
|
|
185
|
+
npm install
|
|
186
|
+
npm run build
|
|
187
|
+
npm run test:offline
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### **Available Scripts**
|
|
191
|
+
```bash
|
|
192
|
+
npm run build # Build TypeScript
|
|
193
|
+
npm run test # Run all tests
|
|
194
|
+
npm run test:offline # Run tests without API calls
|
|
195
|
+
npm run lint # Check code style
|
|
196
|
+
npm run check # Full quality check
|
|
197
|
+
```
|
|
98
198
|
|
|
99
199
|
## 🤝 Contributing
|
|
100
200
|
|
|
101
|
-
|
|
201
|
+
We welcome contributions! Please see our [Contributing Guidelines](./CONTRIB.md) for details on:
|
|
202
|
+
|
|
203
|
+
- Adding new tools and features
|
|
204
|
+
- Improving documentation
|
|
205
|
+
- Reporting bugs and requesting features
|
|
206
|
+
- Testing and quality assurance
|
|
207
|
+
|
|
208
|
+
## 📈 What's Next?
|
|
209
|
+
|
|
210
|
+
This initial release provides a solid foundation for CRM automation. Future versions will include:
|
|
211
|
+
|
|
212
|
+
- **Enhanced AI Insights**: AI-powered data analysis and recommendations
|
|
213
|
+
- **Custom Workflow Builders**: Visual workflow creation for complex automations
|
|
214
|
+
- **Advanced Reporting**: Comprehensive analytics and dashboard integrations
|
|
215
|
+
- **Third-Party Integrations**: HubSpot, Salesforce, and other CRM sync capabilities
|
|
216
|
+
|
|
217
|
+
## 🔗 Links
|
|
218
|
+
|
|
219
|
+
- **NPM Package**: https://www.npmjs.com/package/attio-mcp
|
|
220
|
+
- **GitHub Repository**: https://github.com/kesslerio/attio-mcp-server
|
|
221
|
+
- **Issues & Support**: https://github.com/kesslerio/attio-mcp-server/issues
|
|
222
|
+
- **Releases**: https://github.com/kesslerio/attio-mcp-server/releases
|
|
223
|
+
- **Attio Documentation**: https://developers.attio.com/
|
|
102
224
|
|
|
103
225
|
## 📄 License
|
|
104
226
|
|
|
105
|
-
This project is licensed under the
|
|
227
|
+
This project is licensed under the **Apache License 2.0** - see the [LICENSE](LICENSE) file for details.
|
|
228
|
+
|
|
229
|
+
**Original Work Attribution**: This project is based on initial work by @hmk under BSD-3-Clause license, with substantial modifications and enhancements by @kesslerio. The original BSD license notice is preserved in the LICENSE file as required.
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
**Ready to transform your CRM workflow?** Install Attio MCP Server today and experience the future of CRM automation with AI!
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
npm install -g attio-mcp
|
|
237
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "attio-mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "A Model Context Protocol server that connects Attio to LLMs",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"module": "dist/index.js",
|
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
"test:search": "node test/api/search.test.js",
|
|
43
43
|
"test:lists": "node test/objects/lists.test.js",
|
|
44
44
|
"setup-hooks": "chmod +x build/install-hooks.sh && ./build/install-hooks.sh",
|
|
45
|
-
"postinstall": "npm run setup-hooks",
|
|
45
|
+
"postinstall": "[ -d .git ] && npm run setup-hooks || echo 'Skipping git hooks setup (not a git repository)'",
|
|
46
46
|
"test-hooks": "chmod +x build/test-hooks.sh && ./build/test-hooks.sh",
|
|
47
47
|
"docker:build": "chmod +x scripts/docker-build.sh && ./scripts/docker-build.sh",
|
|
48
48
|
"docker:run": "docker run -p 3000:3000 -e ATTIO_API_KEY=${ATTIO_API_KEY} -e ATTIO_WORKSPACE_ID=${ATTIO_WORKSPACE_ID} attio-mcp-server:latest",
|