mcp-sharepoint-us 2.0.0__tar.gz
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.
Potentially problematic release.
This version of mcp-sharepoint-us might be problematic. Click here for more details.
- mcp_sharepoint_us-2.0.0/LICENSE +21 -0
- mcp_sharepoint_us-2.0.0/PKG-INFO +359 -0
- mcp_sharepoint_us-2.0.0/README.md +328 -0
- mcp_sharepoint_us-2.0.0/pyproject.toml +56 -0
- mcp_sharepoint_us-2.0.0/setup.cfg +4 -0
- mcp_sharepoint_us-2.0.0/src/mcp_sharepoint/__init__.py +535 -0
- mcp_sharepoint_us-2.0.0/src/mcp_sharepoint/__main__.py +8 -0
- mcp_sharepoint_us-2.0.0/src/mcp_sharepoint/auth.py +234 -0
- mcp_sharepoint_us-2.0.0/src/mcp_sharepoint_us.egg-info/PKG-INFO +359 -0
- mcp_sharepoint_us-2.0.0/src/mcp_sharepoint_us.egg-info/SOURCES.txt +12 -0
- mcp_sharepoint_us-2.0.0/src/mcp_sharepoint_us.egg-info/dependency_links.txt +1 -0
- mcp_sharepoint_us-2.0.0/src/mcp_sharepoint_us.egg-info/entry_points.txt +2 -0
- mcp_sharepoint_us-2.0.0/src/mcp_sharepoint_us.egg-info/requires.txt +11 -0
- mcp_sharepoint_us-2.0.0/src/mcp_sharepoint_us.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 SharePoint MCP Server Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcp-sharepoint-us
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: SharePoint MCP Server with Modern Azure AD Authentication
|
|
5
|
+
License: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/mdev26/mcp-sharepoint
|
|
7
|
+
Project-URL: Repository, https://github.com/mdev26/mcp-sharepoint
|
|
8
|
+
Project-URL: Bug Tracker, https://github.com/mdev26/mcp-sharepoint/issues
|
|
9
|
+
Keywords: mcp,sharepoint,microsoft,azure,office365,msal
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: mcp>=1.0.0
|
|
21
|
+
Requires-Dist: office365-rest-python-client>=2.5.0
|
|
22
|
+
Requires-Dist: msal>=1.24.0
|
|
23
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
24
|
+
Requires-Dist: pydantic>=2.0.0
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
27
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
28
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
29
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# SharePoint MCP Server - Updated with Modern Authentication
|
|
33
|
+
|
|
34
|
+
[](https://opensource.org/licenses/MIT)
|
|
35
|
+
|
|
36
|
+
A comprehensive MCP Server for seamless integration with Microsoft SharePoint, **now with modern Azure AD authentication support** to work with new tenants.
|
|
37
|
+
|
|
38
|
+
## ๐ What's New in v2.0
|
|
39
|
+
|
|
40
|
+
This is an updated fork of the original [mcp-sharepoint](https://github.com/Sofias-ai/mcp-sharepoint) that fixes the `Acquire app-only access token failed` error by implementing modern Azure AD authentication methods.
|
|
41
|
+
|
|
42
|
+
### Key Updates
|
|
43
|
+
|
|
44
|
+
- โ
**Modern MSAL Authentication**: Uses Microsoft Authentication Library (MSAL) for Azure AD
|
|
45
|
+
- โ
**Multiple Auth Methods**: Supports MSAL, certificate-based, and legacy authentication
|
|
46
|
+
- โ
**New Tenant Compatible**: Works out-of-the-box with new Microsoft 365 tenants
|
|
47
|
+
- โ
**Better Error Messages**: Clear guidance when authentication fails
|
|
48
|
+
- โ
**Tenant ID Required**: Properly implements Azure AD app-only authentication
|
|
49
|
+
|
|
50
|
+
## ๐ง The Problem This Fixes
|
|
51
|
+
|
|
52
|
+
The original mcp-sharepoint used the deprecated ACS (Azure Access Control Service) authentication method with `with_client_credentials()`. This fails on new tenants with:
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
ValueError: Acquire app-only access token failed
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Why this happens:**
|
|
59
|
+
- Microsoft disabled ACS app-only authentication by default for new tenants
|
|
60
|
+
- The old method doesn't include tenant ID in the authentication flow
|
|
61
|
+
- Modern Azure AD authentication requires MSAL or certificate-based auth
|
|
62
|
+
|
|
63
|
+
**This update solves it by:**
|
|
64
|
+
- Using MSAL (Microsoft Authentication Library) by default
|
|
65
|
+
- Properly passing tenant ID to Azure AD
|
|
66
|
+
- Supporting multiple modern authentication methods
|
|
67
|
+
- Falling back gracefully with helpful error messages
|
|
68
|
+
|
|
69
|
+
## ๐ Prerequisites
|
|
70
|
+
|
|
71
|
+
### Azure AD App Registration
|
|
72
|
+
|
|
73
|
+
You need to register an application in Azure AD with the following:
|
|
74
|
+
|
|
75
|
+
1. **Go to Azure Portal** โ Azure Active Directory โ App registrations
|
|
76
|
+
2. **Create new registration**:
|
|
77
|
+
- Name: "SharePoint MCP Server" (or your choice)
|
|
78
|
+
- Supported account types: "Accounts in this organizational directory only"
|
|
79
|
+
- Redirect URI: Not needed for app-only auth
|
|
80
|
+
|
|
81
|
+
3. **Configure API Permissions**:
|
|
82
|
+
- Click "API permissions" โ "Add a permission"
|
|
83
|
+
- Choose "SharePoint" โ "Application permissions"
|
|
84
|
+
- Add these permissions:
|
|
85
|
+
- `Sites.Read.All` (for read operations)
|
|
86
|
+
- `Sites.ReadWrite.All` (for write operations)
|
|
87
|
+
- **Important**: Click "Grant admin consent" for your organization
|
|
88
|
+
|
|
89
|
+
4. **Create Client Secret**:
|
|
90
|
+
- Go to "Certificates & secrets"
|
|
91
|
+
- Click "New client secret"
|
|
92
|
+
- Choose expiration (recommend 24 months)
|
|
93
|
+
- **Save the secret value immediately** (you won't see it again)
|
|
94
|
+
|
|
95
|
+
5. **Note these values**:
|
|
96
|
+
- Application (client) ID
|
|
97
|
+
- Directory (tenant) ID
|
|
98
|
+
- Client secret value
|
|
99
|
+
|
|
100
|
+
### Required Information
|
|
101
|
+
|
|
102
|
+
You'll need:
|
|
103
|
+
- **Tenant ID**: Your Azure AD tenant ID (GUID)
|
|
104
|
+
- **Client ID**: Your Azure AD application ID (GUID)
|
|
105
|
+
- **Client Secret**: The secret value you created
|
|
106
|
+
- **Site URL**: Your SharePoint site URL (e.g., `https://contoso.sharepoint.com/sites/yoursite`)
|
|
107
|
+
|
|
108
|
+
## ๐ Installation
|
|
109
|
+
|
|
110
|
+
### From Source (Recommended for this fork)
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
# Clone this repository
|
|
114
|
+
git clone https://github.com/your-username/mcp-sharepoint-updated.git
|
|
115
|
+
cd mcp-sharepoint-updated
|
|
116
|
+
|
|
117
|
+
# Install in development mode
|
|
118
|
+
pip install -e .
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Using uv (Alternative)
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
uv pip install -e .
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## โ๏ธ Configuration
|
|
128
|
+
|
|
129
|
+
### Environment Variables
|
|
130
|
+
|
|
131
|
+
Create a `.env` file or set these environment variables:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
# Required - Modern Authentication
|
|
135
|
+
SHP_TENANT_ID=your-tenant-id-guid
|
|
136
|
+
SHP_ID_APP=your-client-id-guid
|
|
137
|
+
SHP_ID_APP_SECRET=your-client-secret
|
|
138
|
+
SHP_SITE_URL=https://your-tenant.sharepoint.com/sites/your-site
|
|
139
|
+
|
|
140
|
+
# Optional
|
|
141
|
+
SHP_DOC_LIBRARY=Shared Documents
|
|
142
|
+
SHP_AUTH_METHOD=msal # Options: msal (default), certificate, legacy
|
|
143
|
+
|
|
144
|
+
# For certificate-based authentication (optional)
|
|
145
|
+
# SHP_CERT_PATH=/path/to/certificate.pem
|
|
146
|
+
# SHP_CERT_THUMBPRINT=your-cert-thumbprint
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Authentication Methods
|
|
150
|
+
|
|
151
|
+
The server supports three authentication methods:
|
|
152
|
+
|
|
153
|
+
#### 1. MSAL (Recommended - Default)
|
|
154
|
+
Modern Azure AD authentication using MSAL. Works with new tenants.
|
|
155
|
+
```bash
|
|
156
|
+
SHP_AUTH_METHOD=msal
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
#### 2. Certificate-Based
|
|
160
|
+
For organizations requiring certificate authentication.
|
|
161
|
+
```bash
|
|
162
|
+
SHP_AUTH_METHOD=certificate
|
|
163
|
+
SHP_CERT_PATH=/path/to/cert.pem
|
|
164
|
+
SHP_CERT_THUMBPRINT=your-thumbprint
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
#### 3. Legacy (Deprecated)
|
|
168
|
+
Old ACS authentication. Only use if you have an older tenant with ACS enabled.
|
|
169
|
+
```bash
|
|
170
|
+
SHP_AUTH_METHOD=legacy
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## ๐ Claude Desktop Integration
|
|
174
|
+
|
|
175
|
+
### Windows
|
|
176
|
+
Edit: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
177
|
+
|
|
178
|
+
### macOS
|
|
179
|
+
Edit: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
180
|
+
|
|
181
|
+
### Configuration
|
|
182
|
+
|
|
183
|
+
```json
|
|
184
|
+
{
|
|
185
|
+
"mcpServers": {
|
|
186
|
+
"sharepoint": {
|
|
187
|
+
"command": "python",
|
|
188
|
+
"args": ["-m", "mcp_sharepoint"],
|
|
189
|
+
"env": {
|
|
190
|
+
"SHP_TENANT_ID": "your-tenant-id",
|
|
191
|
+
"SHP_ID_APP": "your-client-id",
|
|
192
|
+
"SHP_ID_APP_SECRET": "your-client-secret",
|
|
193
|
+
"SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
|
|
194
|
+
"SHP_DOC_LIBRARY": "Shared Documents",
|
|
195
|
+
"SHP_AUTH_METHOD": "msal"
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Using uvx (Alternative)
|
|
203
|
+
|
|
204
|
+
```json
|
|
205
|
+
{
|
|
206
|
+
"mcpServers": {
|
|
207
|
+
"sharepoint": {
|
|
208
|
+
"command": "uvx",
|
|
209
|
+
"args": ["mcp-sharepoint"],
|
|
210
|
+
"env": {
|
|
211
|
+
"SHP_TENANT_ID": "your-tenant-id",
|
|
212
|
+
"SHP_ID_APP": "your-client-id",
|
|
213
|
+
"SHP_ID_APP_SECRET": "your-client-secret",
|
|
214
|
+
"SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
|
|
215
|
+
"SHP_AUTH_METHOD": "msal"
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## ๐งช Testing the Connection
|
|
223
|
+
|
|
224
|
+
After installation, you can test the connection:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
# Set your environment variables first
|
|
228
|
+
export SHP_TENANT_ID=your-tenant-id
|
|
229
|
+
export SHP_ID_APP=your-client-id
|
|
230
|
+
export SHP_ID_APP_SECRET=your-secret
|
|
231
|
+
export SHP_SITE_URL=https://your-site.sharepoint.com/sites/yoursite
|
|
232
|
+
|
|
233
|
+
# Run the server
|
|
234
|
+
python -m mcp_sharepoint
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
In Claude Desktop, you can use the "Test_Connection" tool to verify everything is working.
|
|
238
|
+
|
|
239
|
+
## ๐ ๏ธ Available Tools
|
|
240
|
+
|
|
241
|
+
The server provides these tools for SharePoint operations:
|
|
242
|
+
|
|
243
|
+
### Document Management
|
|
244
|
+
- `List_SharePoint_Documents` - List all documents in a folder
|
|
245
|
+
- `Get_Document_Content` - Read document content
|
|
246
|
+
- `Upload_Document` - Upload new documents
|
|
247
|
+
- `Update_Document` - Update existing documents
|
|
248
|
+
- `Delete_Document` - Delete documents
|
|
249
|
+
|
|
250
|
+
### Folder Management
|
|
251
|
+
- `List_SharePoint_Folders` - List folders in a directory
|
|
252
|
+
- `Create_Folder` - Create new folders
|
|
253
|
+
- `Delete_Folder` - Delete empty folders
|
|
254
|
+
- `Get_SharePoint_Tree` - Get recursive folder structure
|
|
255
|
+
|
|
256
|
+
### Utilities
|
|
257
|
+
- `Test_Connection` - Test authentication and connection
|
|
258
|
+
|
|
259
|
+
## ๐ Troubleshooting
|
|
260
|
+
|
|
261
|
+
### "Acquire app-only access token failed"
|
|
262
|
+
|
|
263
|
+
**This is the error we're fixing!** If you still see this:
|
|
264
|
+
|
|
265
|
+
1. **Check you're using MSAL**:
|
|
266
|
+
```bash
|
|
267
|
+
SHP_AUTH_METHOD=msal # Make sure this is set
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
2. **Verify tenant ID is correct**:
|
|
271
|
+
- Go to Azure Portal โ Azure Active Directory โ Overview
|
|
272
|
+
- Copy the "Tenant ID" GUID
|
|
273
|
+
- Ensure it matches `SHP_TENANT_ID`
|
|
274
|
+
|
|
275
|
+
3. **Check API permissions**:
|
|
276
|
+
- Azure Portal โ Your App โ API permissions
|
|
277
|
+
- Ensure SharePoint permissions are granted
|
|
278
|
+
- Click "Grant admin consent"
|
|
279
|
+
|
|
280
|
+
4. **Wait for permission propagation**:
|
|
281
|
+
- After granting permissions, wait 5-10 minutes
|
|
282
|
+
- Try again
|
|
283
|
+
|
|
284
|
+
### "Authentication failed"
|
|
285
|
+
|
|
286
|
+
1. **Verify credentials**:
|
|
287
|
+
- Client ID is correct (from App registrations โ Overview)
|
|
288
|
+
- Client secret is correct and not expired
|
|
289
|
+
- Tenant ID is correct
|
|
290
|
+
|
|
291
|
+
2. **Check site URL**:
|
|
292
|
+
- Must be exact SharePoint site URL
|
|
293
|
+
- Should NOT end with a slash
|
|
294
|
+
- Example: `https://contoso.sharepoint.com/sites/marketing`
|
|
295
|
+
|
|
296
|
+
3. **Verify network access**:
|
|
297
|
+
- Ensure you can reach `login.microsoftonline.com` on port 443
|
|
298
|
+
- Check firewall/proxy settings
|
|
299
|
+
|
|
300
|
+
### "Access denied" / "403 Forbidden"
|
|
301
|
+
|
|
302
|
+
1. **Check SharePoint permissions**:
|
|
303
|
+
- API permissions must be **Application** permissions, not Delegated
|
|
304
|
+
- Need `Sites.Read.All` or `Sites.ReadWrite.All`
|
|
305
|
+
- Admin consent must be granted
|
|
306
|
+
|
|
307
|
+
2. **Verify site access**:
|
|
308
|
+
- The app must have access to the specific SharePoint site
|
|
309
|
+
- May need to grant site permissions separately
|
|
310
|
+
|
|
311
|
+
## ๐ Migration from Original mcp-sharepoint
|
|
312
|
+
|
|
313
|
+
If you're migrating from the original version:
|
|
314
|
+
|
|
315
|
+
1. **Add new environment variable**:
|
|
316
|
+
```bash
|
|
317
|
+
SHP_TENANT_ID=your-tenant-id # This is new!
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
2. **Optional: Set auth method explicitly**:
|
|
321
|
+
```bash
|
|
322
|
+
SHP_AUTH_METHOD=msal # Explicitly use modern auth
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
3. **Update your Claude Desktop config**:
|
|
326
|
+
- Add `SHP_TENANT_ID` to the env section
|
|
327
|
+
- Optionally add `SHP_AUTH_METHOD: "msal"`
|
|
328
|
+
|
|
329
|
+
4. **Restart Claude Desktop** to load the new configuration
|
|
330
|
+
|
|
331
|
+
## ๐ค Contributing
|
|
332
|
+
|
|
333
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
334
|
+
|
|
335
|
+
## ๐ License
|
|
336
|
+
|
|
337
|
+
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
338
|
+
|
|
339
|
+
## ๐ Acknowledgments
|
|
340
|
+
|
|
341
|
+
- Original [mcp-sharepoint](https://github.com/Sofias-ai/mcp-sharepoint) by sofias tech
|
|
342
|
+
- [Office365-REST-Python-Client](https://github.com/vgrem/Office365-REST-Python-Client) library
|
|
343
|
+
- Microsoft Authentication Library (MSAL) for Python
|
|
344
|
+
|
|
345
|
+
## ๐ Support
|
|
346
|
+
|
|
347
|
+
If you encounter issues:
|
|
348
|
+
|
|
349
|
+
1. Check the [Troubleshooting](#-troubleshooting) section
|
|
350
|
+
2. Review [Azure AD App Setup](#azure-ad-app-registration)
|
|
351
|
+
3. Open an issue with:
|
|
352
|
+
- Error message (sanitize any secrets!)
|
|
353
|
+
- Your environment (Python version, OS)
|
|
354
|
+
- Authentication method being used
|
|
355
|
+
- Whether it's a new or existing tenant
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
359
|
+
**Note**: This is an updated version that solves the authentication issues with new Microsoft 365 tenants. The original version can be found at [Sofias-ai/mcp-sharepoint](https://github.com/Sofias-ai/mcp-sharepoint).
|
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
# SharePoint MCP Server - Updated with Modern Authentication
|
|
2
|
+
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
|
+
|
|
5
|
+
A comprehensive MCP Server for seamless integration with Microsoft SharePoint, **now with modern Azure AD authentication support** to work with new tenants.
|
|
6
|
+
|
|
7
|
+
## ๐ What's New in v2.0
|
|
8
|
+
|
|
9
|
+
This is an updated fork of the original [mcp-sharepoint](https://github.com/Sofias-ai/mcp-sharepoint) that fixes the `Acquire app-only access token failed` error by implementing modern Azure AD authentication methods.
|
|
10
|
+
|
|
11
|
+
### Key Updates
|
|
12
|
+
|
|
13
|
+
- โ
**Modern MSAL Authentication**: Uses Microsoft Authentication Library (MSAL) for Azure AD
|
|
14
|
+
- โ
**Multiple Auth Methods**: Supports MSAL, certificate-based, and legacy authentication
|
|
15
|
+
- โ
**New Tenant Compatible**: Works out-of-the-box with new Microsoft 365 tenants
|
|
16
|
+
- โ
**Better Error Messages**: Clear guidance when authentication fails
|
|
17
|
+
- โ
**Tenant ID Required**: Properly implements Azure AD app-only authentication
|
|
18
|
+
|
|
19
|
+
## ๐ง The Problem This Fixes
|
|
20
|
+
|
|
21
|
+
The original mcp-sharepoint used the deprecated ACS (Azure Access Control Service) authentication method with `with_client_credentials()`. This fails on new tenants with:
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
ValueError: Acquire app-only access token failed
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
**Why this happens:**
|
|
28
|
+
- Microsoft disabled ACS app-only authentication by default for new tenants
|
|
29
|
+
- The old method doesn't include tenant ID in the authentication flow
|
|
30
|
+
- Modern Azure AD authentication requires MSAL or certificate-based auth
|
|
31
|
+
|
|
32
|
+
**This update solves it by:**
|
|
33
|
+
- Using MSAL (Microsoft Authentication Library) by default
|
|
34
|
+
- Properly passing tenant ID to Azure AD
|
|
35
|
+
- Supporting multiple modern authentication methods
|
|
36
|
+
- Falling back gracefully with helpful error messages
|
|
37
|
+
|
|
38
|
+
## ๐ Prerequisites
|
|
39
|
+
|
|
40
|
+
### Azure AD App Registration
|
|
41
|
+
|
|
42
|
+
You need to register an application in Azure AD with the following:
|
|
43
|
+
|
|
44
|
+
1. **Go to Azure Portal** โ Azure Active Directory โ App registrations
|
|
45
|
+
2. **Create new registration**:
|
|
46
|
+
- Name: "SharePoint MCP Server" (or your choice)
|
|
47
|
+
- Supported account types: "Accounts in this organizational directory only"
|
|
48
|
+
- Redirect URI: Not needed for app-only auth
|
|
49
|
+
|
|
50
|
+
3. **Configure API Permissions**:
|
|
51
|
+
- Click "API permissions" โ "Add a permission"
|
|
52
|
+
- Choose "SharePoint" โ "Application permissions"
|
|
53
|
+
- Add these permissions:
|
|
54
|
+
- `Sites.Read.All` (for read operations)
|
|
55
|
+
- `Sites.ReadWrite.All` (for write operations)
|
|
56
|
+
- **Important**: Click "Grant admin consent" for your organization
|
|
57
|
+
|
|
58
|
+
4. **Create Client Secret**:
|
|
59
|
+
- Go to "Certificates & secrets"
|
|
60
|
+
- Click "New client secret"
|
|
61
|
+
- Choose expiration (recommend 24 months)
|
|
62
|
+
- **Save the secret value immediately** (you won't see it again)
|
|
63
|
+
|
|
64
|
+
5. **Note these values**:
|
|
65
|
+
- Application (client) ID
|
|
66
|
+
- Directory (tenant) ID
|
|
67
|
+
- Client secret value
|
|
68
|
+
|
|
69
|
+
### Required Information
|
|
70
|
+
|
|
71
|
+
You'll need:
|
|
72
|
+
- **Tenant ID**: Your Azure AD tenant ID (GUID)
|
|
73
|
+
- **Client ID**: Your Azure AD application ID (GUID)
|
|
74
|
+
- **Client Secret**: The secret value you created
|
|
75
|
+
- **Site URL**: Your SharePoint site URL (e.g., `https://contoso.sharepoint.com/sites/yoursite`)
|
|
76
|
+
|
|
77
|
+
## ๐ Installation
|
|
78
|
+
|
|
79
|
+
### From Source (Recommended for this fork)
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
# Clone this repository
|
|
83
|
+
git clone https://github.com/your-username/mcp-sharepoint-updated.git
|
|
84
|
+
cd mcp-sharepoint-updated
|
|
85
|
+
|
|
86
|
+
# Install in development mode
|
|
87
|
+
pip install -e .
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Using uv (Alternative)
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
uv pip install -e .
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## โ๏ธ Configuration
|
|
97
|
+
|
|
98
|
+
### Environment Variables
|
|
99
|
+
|
|
100
|
+
Create a `.env` file or set these environment variables:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# Required - Modern Authentication
|
|
104
|
+
SHP_TENANT_ID=your-tenant-id-guid
|
|
105
|
+
SHP_ID_APP=your-client-id-guid
|
|
106
|
+
SHP_ID_APP_SECRET=your-client-secret
|
|
107
|
+
SHP_SITE_URL=https://your-tenant.sharepoint.com/sites/your-site
|
|
108
|
+
|
|
109
|
+
# Optional
|
|
110
|
+
SHP_DOC_LIBRARY=Shared Documents
|
|
111
|
+
SHP_AUTH_METHOD=msal # Options: msal (default), certificate, legacy
|
|
112
|
+
|
|
113
|
+
# For certificate-based authentication (optional)
|
|
114
|
+
# SHP_CERT_PATH=/path/to/certificate.pem
|
|
115
|
+
# SHP_CERT_THUMBPRINT=your-cert-thumbprint
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Authentication Methods
|
|
119
|
+
|
|
120
|
+
The server supports three authentication methods:
|
|
121
|
+
|
|
122
|
+
#### 1. MSAL (Recommended - Default)
|
|
123
|
+
Modern Azure AD authentication using MSAL. Works with new tenants.
|
|
124
|
+
```bash
|
|
125
|
+
SHP_AUTH_METHOD=msal
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
#### 2. Certificate-Based
|
|
129
|
+
For organizations requiring certificate authentication.
|
|
130
|
+
```bash
|
|
131
|
+
SHP_AUTH_METHOD=certificate
|
|
132
|
+
SHP_CERT_PATH=/path/to/cert.pem
|
|
133
|
+
SHP_CERT_THUMBPRINT=your-thumbprint
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
#### 3. Legacy (Deprecated)
|
|
137
|
+
Old ACS authentication. Only use if you have an older tenant with ACS enabled.
|
|
138
|
+
```bash
|
|
139
|
+
SHP_AUTH_METHOD=legacy
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## ๐ Claude Desktop Integration
|
|
143
|
+
|
|
144
|
+
### Windows
|
|
145
|
+
Edit: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
146
|
+
|
|
147
|
+
### macOS
|
|
148
|
+
Edit: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
149
|
+
|
|
150
|
+
### Configuration
|
|
151
|
+
|
|
152
|
+
```json
|
|
153
|
+
{
|
|
154
|
+
"mcpServers": {
|
|
155
|
+
"sharepoint": {
|
|
156
|
+
"command": "python",
|
|
157
|
+
"args": ["-m", "mcp_sharepoint"],
|
|
158
|
+
"env": {
|
|
159
|
+
"SHP_TENANT_ID": "your-tenant-id",
|
|
160
|
+
"SHP_ID_APP": "your-client-id",
|
|
161
|
+
"SHP_ID_APP_SECRET": "your-client-secret",
|
|
162
|
+
"SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
|
|
163
|
+
"SHP_DOC_LIBRARY": "Shared Documents",
|
|
164
|
+
"SHP_AUTH_METHOD": "msal"
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Using uvx (Alternative)
|
|
172
|
+
|
|
173
|
+
```json
|
|
174
|
+
{
|
|
175
|
+
"mcpServers": {
|
|
176
|
+
"sharepoint": {
|
|
177
|
+
"command": "uvx",
|
|
178
|
+
"args": ["mcp-sharepoint"],
|
|
179
|
+
"env": {
|
|
180
|
+
"SHP_TENANT_ID": "your-tenant-id",
|
|
181
|
+
"SHP_ID_APP": "your-client-id",
|
|
182
|
+
"SHP_ID_APP_SECRET": "your-client-secret",
|
|
183
|
+
"SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
|
|
184
|
+
"SHP_AUTH_METHOD": "msal"
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## ๐งช Testing the Connection
|
|
192
|
+
|
|
193
|
+
After installation, you can test the connection:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
# Set your environment variables first
|
|
197
|
+
export SHP_TENANT_ID=your-tenant-id
|
|
198
|
+
export SHP_ID_APP=your-client-id
|
|
199
|
+
export SHP_ID_APP_SECRET=your-secret
|
|
200
|
+
export SHP_SITE_URL=https://your-site.sharepoint.com/sites/yoursite
|
|
201
|
+
|
|
202
|
+
# Run the server
|
|
203
|
+
python -m mcp_sharepoint
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
In Claude Desktop, you can use the "Test_Connection" tool to verify everything is working.
|
|
207
|
+
|
|
208
|
+
## ๐ ๏ธ Available Tools
|
|
209
|
+
|
|
210
|
+
The server provides these tools for SharePoint operations:
|
|
211
|
+
|
|
212
|
+
### Document Management
|
|
213
|
+
- `List_SharePoint_Documents` - List all documents in a folder
|
|
214
|
+
- `Get_Document_Content` - Read document content
|
|
215
|
+
- `Upload_Document` - Upload new documents
|
|
216
|
+
- `Update_Document` - Update existing documents
|
|
217
|
+
- `Delete_Document` - Delete documents
|
|
218
|
+
|
|
219
|
+
### Folder Management
|
|
220
|
+
- `List_SharePoint_Folders` - List folders in a directory
|
|
221
|
+
- `Create_Folder` - Create new folders
|
|
222
|
+
- `Delete_Folder` - Delete empty folders
|
|
223
|
+
- `Get_SharePoint_Tree` - Get recursive folder structure
|
|
224
|
+
|
|
225
|
+
### Utilities
|
|
226
|
+
- `Test_Connection` - Test authentication and connection
|
|
227
|
+
|
|
228
|
+
## ๐ Troubleshooting
|
|
229
|
+
|
|
230
|
+
### "Acquire app-only access token failed"
|
|
231
|
+
|
|
232
|
+
**This is the error we're fixing!** If you still see this:
|
|
233
|
+
|
|
234
|
+
1. **Check you're using MSAL**:
|
|
235
|
+
```bash
|
|
236
|
+
SHP_AUTH_METHOD=msal # Make sure this is set
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
2. **Verify tenant ID is correct**:
|
|
240
|
+
- Go to Azure Portal โ Azure Active Directory โ Overview
|
|
241
|
+
- Copy the "Tenant ID" GUID
|
|
242
|
+
- Ensure it matches `SHP_TENANT_ID`
|
|
243
|
+
|
|
244
|
+
3. **Check API permissions**:
|
|
245
|
+
- Azure Portal โ Your App โ API permissions
|
|
246
|
+
- Ensure SharePoint permissions are granted
|
|
247
|
+
- Click "Grant admin consent"
|
|
248
|
+
|
|
249
|
+
4. **Wait for permission propagation**:
|
|
250
|
+
- After granting permissions, wait 5-10 minutes
|
|
251
|
+
- Try again
|
|
252
|
+
|
|
253
|
+
### "Authentication failed"
|
|
254
|
+
|
|
255
|
+
1. **Verify credentials**:
|
|
256
|
+
- Client ID is correct (from App registrations โ Overview)
|
|
257
|
+
- Client secret is correct and not expired
|
|
258
|
+
- Tenant ID is correct
|
|
259
|
+
|
|
260
|
+
2. **Check site URL**:
|
|
261
|
+
- Must be exact SharePoint site URL
|
|
262
|
+
- Should NOT end with a slash
|
|
263
|
+
- Example: `https://contoso.sharepoint.com/sites/marketing`
|
|
264
|
+
|
|
265
|
+
3. **Verify network access**:
|
|
266
|
+
- Ensure you can reach `login.microsoftonline.com` on port 443
|
|
267
|
+
- Check firewall/proxy settings
|
|
268
|
+
|
|
269
|
+
### "Access denied" / "403 Forbidden"
|
|
270
|
+
|
|
271
|
+
1. **Check SharePoint permissions**:
|
|
272
|
+
- API permissions must be **Application** permissions, not Delegated
|
|
273
|
+
- Need `Sites.Read.All` or `Sites.ReadWrite.All`
|
|
274
|
+
- Admin consent must be granted
|
|
275
|
+
|
|
276
|
+
2. **Verify site access**:
|
|
277
|
+
- The app must have access to the specific SharePoint site
|
|
278
|
+
- May need to grant site permissions separately
|
|
279
|
+
|
|
280
|
+
## ๐ Migration from Original mcp-sharepoint
|
|
281
|
+
|
|
282
|
+
If you're migrating from the original version:
|
|
283
|
+
|
|
284
|
+
1. **Add new environment variable**:
|
|
285
|
+
```bash
|
|
286
|
+
SHP_TENANT_ID=your-tenant-id # This is new!
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
2. **Optional: Set auth method explicitly**:
|
|
290
|
+
```bash
|
|
291
|
+
SHP_AUTH_METHOD=msal # Explicitly use modern auth
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
3. **Update your Claude Desktop config**:
|
|
295
|
+
- Add `SHP_TENANT_ID` to the env section
|
|
296
|
+
- Optionally add `SHP_AUTH_METHOD: "msal"`
|
|
297
|
+
|
|
298
|
+
4. **Restart Claude Desktop** to load the new configuration
|
|
299
|
+
|
|
300
|
+
## ๐ค Contributing
|
|
301
|
+
|
|
302
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
303
|
+
|
|
304
|
+
## ๐ License
|
|
305
|
+
|
|
306
|
+
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
307
|
+
|
|
308
|
+
## ๐ Acknowledgments
|
|
309
|
+
|
|
310
|
+
- Original [mcp-sharepoint](https://github.com/Sofias-ai/mcp-sharepoint) by sofias tech
|
|
311
|
+
- [Office365-REST-Python-Client](https://github.com/vgrem/Office365-REST-Python-Client) library
|
|
312
|
+
- Microsoft Authentication Library (MSAL) for Python
|
|
313
|
+
|
|
314
|
+
## ๐ Support
|
|
315
|
+
|
|
316
|
+
If you encounter issues:
|
|
317
|
+
|
|
318
|
+
1. Check the [Troubleshooting](#-troubleshooting) section
|
|
319
|
+
2. Review [Azure AD App Setup](#azure-ad-app-registration)
|
|
320
|
+
3. Open an issue with:
|
|
321
|
+
- Error message (sanitize any secrets!)
|
|
322
|
+
- Your environment (Python version, OS)
|
|
323
|
+
- Authentication method being used
|
|
324
|
+
- Whether it's a new or existing tenant
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
**Note**: This is an updated version that solves the authentication issues with new Microsoft 365 tenants. The original version can be found at [Sofias-ai/mcp-sharepoint](https://github.com/Sofias-ai/mcp-sharepoint).
|