# sharepoint-lists MCP server

An [MCP](https://modelcontextprotocol.io) server exposing Microsoft SharePoint
Lists as tools, using app-only (client-credentials) Microsoft Graph auth. It
reuses the same core client as the skill
(`../.claude/skills/sharepoint-lists/scripts/lib/graph.mjs`) — one source of
truth for the Graph logic.

**Transport: stdio only.** This server is meant to run locally and be launched
by a local Claude app (Claude Desktop / Claude Code / Cowork). It has no network
listener by design, so it cannot be reached remotely or from web chat.

## Tools

| Tool | Access | Purpose |
|---|---|---|
| `sharepoint_test` | read | Verify credentials; with a site, list its lists |
| `sharepoint_list_lists` | read | Enumerate lists in a site |
| `sharepoint_get_columns` | read | Column internal names + types (call before writing) |
| `sharepoint_list_items` | read | Query items (filter/select/orderby/top/all) |
| `sharepoint_get_item` | read | Get one item by id |
| `sharepoint_create_item` | write | Create an item |
| `sharepoint_update_item` | write | Update an item (partial) |
| `sharepoint_delete_item` | write | Delete an item (irreversible) |

Set `SP_READONLY=true` to register only the read tools.

## Setup

```bash
cd mcp-server
npm install
cp .env.example .env      # then fill in SP_TENANT_ID / SP_CLIENT_ID / SP_CLIENT_SECRET
```

Credentials and the optional `SP_SITE_URL` default are documented in
`../.claude/skills/sharepoint-lists/references/setup.md`. The server loads
`mcp-server/.env` automatically (by its own path), so the client app does not
need to pass credentials.

## Connect it

### Claude Desktop (primary)
Add an entry to `claude_desktop_config.json`
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS),
then fully quit and reopen Claude Desktop:

```json
{
  "mcpServers": {
    "sharepoint-lists": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/Claude-SharepointLists/mcp-server/index.mjs"]
    }
  }
}
```

Use the absolute path to `node` (Claude Desktop doesn't inherit your shell PATH).

### Claude Code
The project `.mcp.json` at the repo root already registers this server; from the
repo root, Claude Code will offer to start it. Ensure `mcp-server/.env` is filled in.

## Notes

- App-only auth means there is no per-user permission check — every caller acts
  as the app. Keeping this stdio-only (no network listener) is the intended
  containment.
- Field formats for writes (person/lookup/choice/date) are documented in
  `../.claude/skills/sharepoint-lists/references/graph-api.md`.