{"id":"3a06a6a7-bd07-4f2c-8e62-81bf45d8410f","slug":"sourceplane-mcp","kind":"mcp","name":"sourceplane-mcp","summary":"Secure multi-source MCP server for local repositories, GitHub, GitLab, and Bitbucket","owner":"infraws","repoUrl":"https://github.com/infraws/sourceplane-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-11T12:37:17.000Z","addedAt":"2026-10-21T06:04:53.818Z","logoUrl":"https://avatars.githubusercontent.com/u/83135955?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","search","files-documents"],"tags":["ai","anthropic","bitbucket","claude","code-search","developer-tools","filesystem","github"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T06:05:25.602Z","sample":false,"url":"https://conduits.dev/tools/sourceplane-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"sourceplane-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Sourceplane MCP\n\n![CI](https://img.shields.io/github/actions/workflow/status/infraWS/sourceplane-mcp/ci.yml?branch=main)\n![Coverage](https://img.shields.io/badge/coverage-76%25-brightgreen)\n![License](https://img.shields.io/github/license/infraWS/sourceplane-mcp)\n![Node](https://img.shields.io/badge/node-%3E%3D20-blue)\n![MCP](https://img.shields.io/badge/MCP-compatible-purple)\n\nSecure multi-source MCP server for local repositories, GitHub, GitLab, Bitbucket, and mounted network workspaces.\n\nSourceplane MCP provides a consistent Model Context Protocol interface for safely exposing source code and documentation to MCP-compatible AI clients such as Claude Desktop.\n\nThe platform is read-only by default, with optional local-only development write support.\n\nIt is designed specifically for source context and repository inspection — not platform automation.\n\n---\n\n## Why Sourceplane MCP Exists\n\nModern engineering environments are fragmented across:\n\n- frontend repositories\n- backend services\n- infrastructure repositories\n- shared libraries\n- monorepos\n- local workspaces\n- mounted NAS shares\n- self-hosted Git providers\n- documentation repositories\n\nAI assistants are significantly more useful when they can safely inspect source trees directly instead of relying on manual copy/paste.\n\nSourceplane MCP focuses on:\n\n- read-only-by-default access\n- explicit source allowlisting\n- filesystem safety\n- secure defaults\n- self-hosted provider support\n- local-first workflows\n- predictable behavior\n- low operational complexity\n- easy auditing\n\n---\n\n## Supported Sources\n\n| Source Type | Description | Token Required |\n|---|---|---|\n| `github` | GitHub repository via API | Optional for public repos |\n| `gitlab` | GitLab project via API | Optional for public projects |\n| `bitbucket` | Bitbucket Cloud or Data Center repository | Optional for public repos |\n| `local` | Local workspace folder | No |\n| `network` | Mounted NAS or network share | No |\n\nNetwork sources are mounted filesystem paths such as:\n\n```text\n/Volumes/Engineering/shared-platform\n/mnt/shared/platform\n```\n\nThey are not arbitrary internet URLs.\n\n---\n\n## Current Capability Matrix\n\n| Capability | GitHub | GitLab | Bitbucket Cloud | Bitbucket Data Center | Local | Network |\n|---|---:|---:|---:|---:|---:|---:|\n| Public source without token | Yes | Yes | Yes | Usually internal only | N/A | N/A |\n| Private source with token | Yes | Yes | Yes | Yes | N/A | N/A |\n| Custom `host` | Yes | Yes | Yes | Yes | N/A | N/A |\n| Custom `webUrl` | Yes | Yes | Yes | Yes | N/A | N/A |\n| `list_sources` | Yes | Yes | Yes | Yes | Yes | Yes |\n| `read_file` | Yes | Yes | Yes | Yes | Yes | Yes |\n| `read_files` | Yes | Yes | Yes | Yes | Yes | Yes |\n| `list_files` | Yes | Yes | Yes | Yes | Yes | Yes |\n| `get_source_structure` | Yes | Yes | Yes | Yes | Yes | Yes |\n| `search_code` | API search | API search / tree search | Tree-based search | Tree-based search | Local scan | Local scan |\n| Branch override | Yes | Yes | Yes | Yes | No | No |\n| Built-in blocklist | Yes | Yes | Yes | Yes | Yes | Yes |\n| Source-specific blocklist | Yes | Yes | Yes | Yes | Yes | Yes |\n| Write operations | No | No | No | No | Optional local-only | No |\n\n---\n\n## Available MCP Tools\n\n| Tool | Description |\n|---|---|\n| `list_sources` | List configured sources |\n| `read_file` | Read a single file |\n| `read_files` | Read multiple files |\n| `list_files` | List files in a directory |\n| `get_source_structure` | Get recursive source tree |\n| `search_code` | Search source code |\n| `write_file` | Write a UTF-8 text file to an explicitly writable local source |\n\nAll tools use the same source-key model:\n\n```json\n{\n  \"sourceKey\": \"platform-api\",\n  \"path\": \"src/index.ts\"\n}\n```\n\n---\n\n## Installation\n\n### Requirements\n\n- Node.js 20+\n- npm\n\nOptional:\n- Git provider tokens for private repositories\n\n### Clone Repository\n\n```bash\ngit clone https://github.com/infraWS/sourceplane-mcp.git\n\ncd sourceplane-mcp\n```\n\n### Install Dependencies\n\n```bash\nnpm install\n```\n\n### Build\n\n```bash\nnpm run build\n```\n\n---\n\n## Configuration\n\nCopy the example configuration:\n\n```bash\ncp config/sources.example.yaml config/sources.yaml\n```\n\n`config/sources.yaml` is intentionally gitignored.\n\n---\n\n## Example Configuration\n\n```yaml\nserver:\n  name: sourceplane-mcp\n  version: 1.0.0\n\ndefaults:\n  owner: my-org\n  defaultBranch: main\n\n  maxFileSizeKb: 512\n  maxFiles: 1000\n\n  followSymlinks: false\n\n  pathBlocklist:\n    - .env\n    - .env.*\n    - secrets/\n    - certificates/\n    - private/\n    - \"*.pem\"\n    - \"*.key\"\n    - \"*.p12\"\n    - terraform.tfstate\n    - terraform.tfstate.*\n    - \"*.tfvars\"\n\nsources:\n\n  github-public:\n    type: github\n    owner: nodejs\n    name: node\n\n  github-private:\n    type: github\n    name: terraform-platform\n    token: ${GITHUB_TOKEN}\n\n  github-enterprise:\n    type: github\n    host: https://github.company.com/api/v3\n    webUrl: https://github.company.com\n\n    owner: platform\n    name: terraform-platform\n\n    token: ${GITHUB_ENTERPRISE_TOKEN}\n\n  gitlab-public:\n    type: gitlab\n    projectId: gitlab-org/gitlab\n\n  gitlab-private:\n    type: gitlab\n    projectId: platform/backend-api\n    token: ${GITLAB_TOKEN}\n\n  gitlab-self-managed:\n    type: gitlab\n    host: https://gitlab.company.com\n    webUrl: https://gitlab.company.com\n\n    projectId: platform/backend-api\n\n    token: ${GITLAB_SELF_MANAGED_TOKEN}\n\n  bitbucket-cloud:\n    type: bitbucket\n    workspace: engineering\n    slug: frontend-app\n\n    token: ${BITBUCKET_TOKEN}\n\n  bitbucket-datacenter:\n    type: bitbucket\n    host: https://bitbucket.company.com/rest/api/1.0\n    webUrl: https://bitbucket.company.com\n\n    projectKey: PLATFORM\n    slug: frontend-app\n\n    token: ${BITBUCKET_DC_TOKEN}\n\n  local-api:\n    type: local\n    path: ~/Projects/api-service\n\n    write:\n      enabled: false\n      allowOverwrite: false\n      createDirs: false\n\n  shared-network:\n    type: network\n    path: /Volumes/Engineering/shared-platform\n```\n\n---\n\n## Local Development Write Support\n\nSourceplane MCP is read-only by default.\n\nLocal filesystem sources can explicitly opt into controlled write access for development workflows.\n\nWrite support is:\n\n- disabled by default\n- available only for `local` sources\n- not supported for Git providers\n- not supported for network sources\n- protected by the same path safety and blocklist rules as read operations\n\nSupported operations:\n\n- UTF-8 text file writes\n- optional overwrites\n- optional parent directory creation\n\nUnsupported operations:\n\n- file deletion\n- renames\n- shell execution\n- binary writes\n- permission modification\n\n### Example Writable Local Source\n\n```yaml\nsources:\n\n  local-dev:\n    type: local\n    path: ~/Projects/my-app\n\n    write:\n      enabled: true\n      allowOverwrite: true\n      createDirs: true\n```\n\n### Example `write_file`\n\n```json\n{\n  \"sourceKey\": \"local-dev\",\n  \"path\": \"src/generated/example.ts\",\n  \"content\": \"export const example = true;\\n\"\n}\n```\n---\n\n## Security Model\n\nSourceplane MCP is intentionally restrictive.\n\nIt does not:\n\n- write files outside explicitly writable local sources\n- create commits\n- open pull requests\n- merge pull requests\n- execute shell commands\n- trigger CI/CD workflows\n- access arbitrary repositories\n- access arbitrary filesystem paths\n- expose provider secrets\n- modify repositories\n\nOnly explicitly configured sources are accessible.\n\nEven when write support is enabled for local sources, writes remain constrained to the configured source root and continue to enforce:\n\n- traversal protection\n- blocklist enforcement\n- binary detection\n- path normalization\n- UTF-8 text-only writes\n\n---\n\n## Built-in Security Protections\n\n### Path Validation\n\nThe server rejects:\n\n- parent traversal (`../`)\n- absolute paths (`/etc/passwd`)\n- double slashes (`//`)\n- Windows backslashes (`\\`)\n- URL-encoded traversal attempts (`%2e`, `%2f`, `%5c`)\n- null-byte injection attempts\n\n### Built-in Blocklist\n\nThe server always applies an internal protection layer.\n\nExamples include:\n\n- `.git/`\n- `.wrangler/`\n- `node_modules/`\n- `.env`\n- Terraform state files\n- SSH folders\n- certificates\n- private keys\n- generated artifacts\n\nBlocklists are merged in this order:\n\n```text\nDEFAULT_PATH_BLOCKLIST\n→ defaults.pathBlocklist\n→ source.pathBlocklist\n```\n\n### Binary File Protection\n\nThe server refuses to read binary files using:\n\n- extension-based filtering\n- content-based binary detection\n\n### Filesystem Isolation\n\nLocal and network sources are constrained to their configured root path.\n\nExample rejected request:\n\n```json\n{\n  \"sourceKey\": \"local-api\",\n  \"path\": \"../../.ssh/id_rsa\"\n}\n```\n\nSymlinks are disabled by default:\n\n```yaml\ndefaults:\n  followSymlinks: false\n```\n\n---\n\n## Claude Desktop Setup\n\nmacOS Claude Desktop configuration path:\n\n```text\n~/Library/Application Support/Claude/claude_desktop_config.json\n```\n\nExample:\n\n```json\n{\n  \"mcpServers\": {\n    \"sourceplane-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/absolute/path/to/sourceplane-mcp/dist/index.js\"\n      ],\n      \"env\": {\n        \"SOURCEPLANE_CONFIG\": \"/absolute/path/to/sourceplane-mcp/config/sources.yaml\",\n        \"GITHUB_TOKEN\": \"github_pat_xxx\",\n        \"GITLAB_TOKEN\": \"glpat_xxx\",\n        \"BITBUCKET_TOKEN\": \"xxx\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after updating the configuration.\n\n---\n\n## Automated Testing\n\nSourceplane MCP includes automated tests covering:\n\n- traversal rejection\n- nested blocklist enforcement\n- filesystem isolation\n- sanitized error handling\n- binary detection\n- provider URL construction\n- GitLab provider behavior\n- Bitbucket Cloud behavior\n- Bitbucket Data Center behavior\n- local source scanning\n\nCurrent coverage includes:\n\n- high coverage for security-critical logic\n- mocked provider API tests\n- CI validation on Node.js 20 and 22\n\nRun tests:\n\n```bash\nnpm run test\nnpm run coverage\n```\n\n---\n\n## Scripts\n\n```bash\nnpm run dev\nnpm run build\nnpm run start\nnpm run clean\nnpm run test\nnpm run coverage\n```\n\n---\n\n## Design Principles\n\nSourceplane MCP favors:\n\n- explicit configuration\n- least privilege\n- read-only-by-default access\n- secure defaults\n- predictable behavior\n- local-first workflows\n- self-hosted provider support\n- easy auditing\n\nIt is intentionally narrower in scope than platform-automation MCP servers.\n\n---\n\n## License\n\nMIT License"}