MCP OneDrive/SharePoint Server

MCP server and CLI for Microsoft Graph focused on OneDrive, SharePoint and related document workflows. It uses 1Password-provisioned client credentials only, starts with a safe 10-tool core profile, and can opt into advanced tools for trusted automation.

Onboarding commands on a clean clone:

• npm run build

• npm run lint

• npm test

• npm run ci

Tool profiles

The server defaults to MCP_TOOL_PROFILE=core, a smaller public surface intended for day-to-day document workflows:

• health_check, list_drives

• discover_sites, resolve_site

• list_files, search_files, get_file_metadata

• download_file, upload_file, create_folder

Set MCP_TOOL_PROFILE=full to expose advanced and destructive tools for trusted environments:

• Files: list_files, download_file, upload_file, create_folder, move_item, delete_item, search_files, get_file_metadata, share_item, copy_item

• SharePoint: discover_sites, resolve_site, list_site_lists, get_list_schema, list_items, get_list_item, create_list_item, update_list_item, delete_list_item

• Utilities: health_check, get_user_profile, list_drives, global_search

• Advanced: advanced_share, manage_permissions, check_user_access, sync_folder, batch_file_operations, storage_analytics, version_management, excel_operations, excel_analysis

batch_operations is intentionally not part of either profile by default because it is a raw Microsoft Graph escape hatch. Enable it only for admin/debug workflows with MCP_ENABLE_EXPERIMENTAL_GRAPH_BATCH=true.

You can also remove individual tools with MCP_DISABLED_TOOLS=delete_item,manage_permissions.

Related MCP server: OneDrive/SharePoint MCP Server

Why this repo

• one MCP server for both OneDrive and SharePoint document libraries

• matching ods CLI for shell scripting and one-shot automation

• 1Password-only client credentials for interactive and unattended use

• site aliases loaded from a local registry so tenant IDs stay out of git

• pagination/resource helpers for driveId, siteId, itemId and path targeting

Requirements

• Node.js 18+

• A Microsoft Entra ID / Azure AD confidential app registration with Application permissions (Files.ReadWrite.All, Sites.ReadWrite.All) and admin consent. The 1Password owner must provision cpz::SP_CLIENT_ID, cpz::SP_CLIENT_SECRET, and cpz::SP_TENANT_ID; the tenant must be a specific UUID, not common.

Installation

git clone https://github.com/ftaricano/mcp-onedrive-sharepoint.git
cd mcp-onedrive-sharepoint
npm install

Operational wrappers

Important operational rule:

• use this MCP on demand

• do not keep it permanently bound/loaded in Hermes or Claude Code when not needed

• prefer one-shot spcall / mcporter --stdio execution so the process exits right after the call and does not accumulate zombie or idle MCP processes

• the spcall wrapper includes post-call cleanup for stray repo-local MCP child processes

This repo includes lightweight wrappers for local operational use:

• ./scripts/run-stdio.sh: start the MCP stdio server after resolving required values from 1Password

• ./scripts/spcall.sh: run ad-hoc mcporter calls against the local MCP server

• npm run stdio: same as ./scripts/run-stdio.sh

• npm run spcall -- <tool> ...: same as ./scripts/spcall.sh <tool> ...

Quick examples:

npm run build
./scripts/spcall.sh health_check
./scripts/spcall.sh list_drives
./scripts/spcall.sh list_files driveId=b!abc123 path=/Shared%20Documents

Tenant-specific site aliases and drive ids are loaded from a local file — see Site registry below.

CLI (ods)

Every MCP tool is also exposed as a plain subcommand through the ods CLI. It shares the same auth, config and handlers as the MCP server, so anything the MCP does is one-shot runnable from a terminal or a shell script.

npm run build
# `npm install` does NOT put `ods` on your PATH. Link it once, e.g.:
#   npm link            # or: ln -s "$PWD/scripts/ods.sh" ~/bin/ods
ods list                                  # list all tools with descriptions
ods schema list_files                     # print JSON schema for a tool
ods auth                                  # exits: delegated token persistence is intentionally disabled
ods <tool> --key=value [--key value]      # invoke a tool with CLI flags
ods <tool> --json '{"k":"v"}'             # pass the full payload as JSON

During development, rebuild before npm run cli -- <tool> ...; the command uses the same packaged 1Password launcher as the installed ods bin.

Examples

ods health_check
ods list_files --site=primary --path=/
ods list_files --driveId=b!abc --path=/Shared%20Documents --limit=50
ods upload_file --json '{"driveId":"b!abc","path":"/x.txt","content":"hello"}'

Rules for flags

• --key=value and --key value are both accepted.

• true / false / null and numeric strings are coerced automatically; anything else stays a string.

• Bare flags (no value, or followed by another flag) become true.

• --json '<payload>' takes a JSON object; individual --key=value flags layered on top override fields from the payload. Use this for tools with nested objects/arrays (e.g. advanced Excel tools).

• Output is the raw tool payload (usually pretty-printed JSON). If the handler returns an error envelope, the process exits with code 2.

Configuration

The server reads the following environment variables:

# These values are injected only by scripts/with-onepassword-graph-env.sh:
# MICROSOFT_GRAPH_CLIENT_ID
# MICROSOFT_GRAPH_TENANT_ID (specific UUID)
# MICROSOFT_GRAPH_CLIENT_SECRET
MICROSOFT_GRAPH_SCOPES=Files.ReadWrite.All,Sites.ReadWrite.All,Directory.Read.All,User.Read,offline_access
MICROSOFT_GRAPH_BASE_URL=https://graph.microsoft.com/v1.0
MICROSOFT_GRAPH_TIMEOUT=30000
MICROSOFT_GRAPH_MAX_RETRIES=3
MICROSOFT_GRAPH_CACHE_ENABLED=true
MICROSOFT_GRAPH_CACHE_TTL=3600
MCP_TOOL_PROFILE=core
MCP_DISABLED_TOOLS=
MCP_ENABLE_EXPERIMENTAL_GRAPH_BATCH=false

Notes:

• Graph credentials are resolved from 1Password for every supported npm command and packaged bin

• process-local credential variables are reserved for the launcher and tests; .env is never loaded

• set MCP_LOCAL_FILE_ROOT to constrain local upload/download/sync file access; if unset, local paths are constrained to the process working directory

Authentication modes

1Password client credentials

Every supported launcher resolves cpz::SP_CLIENT_ID, cpz::SP_CLIENT_SECRET, and cpz::SP_TENANT_ID through the canonical 1Password helper and injects the values only into its child process. There is no .env, Keychain, file cache, or delegated token fallback. npm run setup-auth and ods auth fail intentionally because the service account cannot persist delegated tokens; request owner-mediated provisioning instead.

Development commands

npm run build
npm run lint
npm test
npm run ci
npm start
npm run stdio
npm run spcall -- health_check

npm run ci is the local verification entrypoint and is also what GitHub Actions runs on every PR/push.

MCP behavior notes

Root site inclusion

discover_sites.includePersonalSite=true currently attempts to append the tenant root SharePoint site (/sites/root) when it is available to the authenticated user. It does not discover or synthesize a personal OneDrive site.

Pagination

The following tools now expose consistent pagination metadata in their JSON payloads:

• list_files

• search_files

• discover_sites

• list_site_lists

• list_items

When Microsoft Graph returns @odata.nextLink, the response includes:

• pagination.returned

• pagination.limit

• pagination.totalCount when available

• pagination.nextPageToken

• pagination.hasMore

Pass pageToken back to the same tool to continue paging.

Drive/site targeting

Core file listing/search/download flows now accept:

• siteId for a SharePoint site's default drive

• driveId for a specific document library or drive

• path-based addressing where supported

This is the current foundation for moving beyond a /me/drive-only model.

Site registry

The resolver can target named SharePoint sites by alias (e.g. site=primary). The registry is loaded from an external JSON file so no tenant-specific ids are committed:

• Copy config/sites.example.json to config/sites.local.json (gitignored) and fill in your values.

• Or set MCP_SITES_CONFIG_PATH to point at a different JSON file.

• If the file is missing, the registry stays empty and the tools only accept explicit siteId, siteUrl, or driveId.

Each site entry looks like:

{
  "key": "primary",
  "name": "Primary",
  "siteId": "yourtenant.sharepoint.com,<guid>,<guid>",
  "siteUrl": "https://yourtenant.sharepoint.com/sites/Primary",
  "driveId": "b!<drive-id>",
  "aliases": ["primary", "/sites/Primary"]
}

MCP stdio snippet

Use the wrapper as the MCP command so Graph credentials are resolved from 1Password:

{
  "mcpServers": {
    "sharepoint": {
      "command": "/absolute/path/to/mcp-onedrive-sharepoint/scripts/run-stdio.sh"
    }
  }
}

Example tool inputs

List files from a specific drive

{
  "driveId": "b!abc123",
  "path": "/Shared Documents",
  "limit": 50
}

Continue a paginated file listing

{
  "driveId": "b!abc123",
  "pageToken": "https://graph.microsoft.com/v1.0/drives/b!abc123/root/children?$skiptoken=..."
}

Search files in a site drive

{
  "siteId": "contoso.sharepoint.com,123,456",
  "query": "quarterly report",
  "limit": 25
}

List SharePoint list items with pagination

{
  "siteId": "contoso.sharepoint.com,123,456",
  "listId": "9c6b8b70-0000-0000-0000-111111111111",
  "orderBy": "Created desc",
  "limit": 100
}

Troubleshooting

• 403 Forbidden on SharePoint lists/drives: the app registration lacks permission to the target site. Check application permissions and admin consent with the owner.

• 404 on a driveId or siteId: the identifier is stale or the resource was deleted. Use list_drives / discover_sites to re-discover.

• Build fails on a clean clone: make sure Node.js is 18+ and run npm install before npm run build.

• AADSTS700016 or 401: ensure the 1Password owner has provisioned a specific tenant UUID (not common) and Application permissions have admin consent in Azure AD.

• AADSTS7000215 (invalid client secret): rotate the secret in the app registration and have the 1Password owner update cpz::SP_CLIENT_SECRET.

Security

This server handles Microsoft Graph client credentials and access to corporate file storage. Treat it accordingly:

• .env, tokens.json, credentials.json, and secret-store exports are never committed — see .gitignore.

• tenant-specific siteId, driveId, SharePoint URLs and internal operational paths should stay in local/private docs, not in this public repo.

• Report security issues privately via GitHub security advisories — do not open a public issue.

• If a client secret leaks, revoke it in Azure AD and ask the 1Password owner to rotate cpz::SP_CLIENT_SECRET.

Contributing

Issues and PRs welcome. Before opening a PR:

• npm run ci passes (build + lint + tests)

• one focused change per PR

• no credentials, tenant-specific ids, or internal paths in commits or README

License

MIT © Fernando Taricano

Current limitations

• client credentials require Application permissions, admin consent, and owner-mediated provisioning in 1Password

• advanced/destructive tools require MCP_TOOL_PROFILE=full

• raw Graph batch calls require MCP_ENABLE_EXPERIMENTAL_GRAPH_BATCH=true