Sourceplane MCP

Secure multi-source MCP server for local repositories, GitHub, GitLab, Bitbucket, and mounted network workspaces.

Sourceplane MCP provides a consistent Model Context Protocol interface for safely exposing source code and documentation to MCP-compatible AI clients such as Claude Desktop.

The platform is read-only by default, with optional local-only development write support.

It is designed specifically for source context and repository inspection — not platform automation.

Why Sourceplane MCP Exists

Modern engineering environments are fragmented across:

• frontend repositories

• backend services

• infrastructure repositories

• shared libraries

• monorepos

• local workspaces

• mounted NAS shares

• self-hosted Git providers

• documentation repositories

AI assistants are significantly more useful when they can safely inspect source trees directly instead of relying on manual copy/paste.

Sourceplane MCP focuses on:

• read-only-by-default access

• explicit source allowlisting

• filesystem safety

• secure defaults

• self-hosted provider support

• local-first workflows

• predictable behavior

• low operational complexity

• easy auditing

Supported Sources

Network sources are mounted filesystem paths such as:

/Volumes/Engineering/shared-platform
/mnt/shared/platform

They are not arbitrary internet URLs.

Current Capability Matrix

Available MCP Tools

All tools use the same source-key model:

{
  "sourceKey": "platform-api",
  "path": "src/index.ts"
}

Installation

Requirements

• Node.js 20+

• npm

Optional:

• Git provider tokens for private repositories

Clone Repository

git clone https://github.com/infraWS/sourceplane-mcp.git

cd sourceplane-mcp

Install Dependencies

npm install

Build

npm run build

Configuration

Copy the example configuration:

cp config/sources.example.yaml config/sources.yaml

config/sources.yaml is intentionally gitignored.

Example Configuration

server:
  name: sourceplane-mcp
  version: 1.0.0

defaults:
  owner: my-org
  defaultBranch: main

  maxFileSizeKb: 512
  maxFiles: 1000

  followSymlinks: false

  pathBlocklist:
    - .env
    - .env.*
    - secrets/
    - certificates/
    - private/
    - "*.pem"
    - "*.key"
    - "*.p12"
    - terraform.tfstate
    - terraform.tfstate.*
    - "*.tfvars"

sources:

  github-public:
    type: github
    owner: nodejs
    name: node

  github-private:
    type: github
    name: terraform-platform
    token: ${GITHUB_TOKEN}

  github-enterprise:
    type: github
    host: https://github.company.com/api/v3
    webUrl: https://github.company.com

    owner: platform
    name: terraform-platform

    token: ${GITHUB_ENTERPRISE_TOKEN}

  gitlab-public:
    type: gitlab
    projectId: gitlab-org/gitlab

  gitlab-private:
    type: gitlab
    projectId: platform/backend-api
    token: ${GITLAB_TOKEN}

  gitlab-self-managed:
    type: gitlab
    host: https://gitlab.company.com
    webUrl: https://gitlab.company.com

    projectId: platform/backend-api

    token: ${GITLAB_SELF_MANAGED_TOKEN}

  bitbucket-cloud:
    type: bitbucket
    workspace: engineering
    slug: frontend-app

    token: ${BITBUCKET_TOKEN}

  bitbucket-datacenter:
    type: bitbucket
    host: https://bitbucket.company.com/rest/api/1.0
    webUrl: https://bitbucket.company.com

    projectKey: PLATFORM
    slug: frontend-app

    token: ${BITBUCKET_DC_TOKEN}

  local-api:
    type: local
    path: ~/Projects/api-service

    write:
      enabled: false
      allowOverwrite: false
      createDirs: false

  shared-network:
    type: network
    path: /Volumes/Engineering/shared-platform

Local Development Write Support

Sourceplane MCP is read-only by default.

Local filesystem sources can explicitly opt into controlled write access for development workflows.

Write support is:

• disabled by default

• available only for local sources

• not supported for Git providers

• not supported for network sources

• protected by the same path safety and blocklist rules as read operations

Supported operations:

• UTF-8 text file writes

• optional overwrites

• optional parent directory creation

Unsupported operations:

• file deletion

• renames

• shell execution

• binary writes

• permission modification

Example Writable Local Source

sources:

  local-dev:
    type: local
    path: ~/Projects/my-app

    write:
      enabled: true
      allowOverwrite: true
      createDirs: true

Example write_file

{
  "sourceKey": "local-dev",
  "path": "src/generated/example.ts",
  "content": "export const example = true;\n"
}

Security Model

Sourceplane MCP is intentionally restrictive.

It does not:

• write files outside explicitly writable local sources

• create commits

• open pull requests

• merge pull requests

• execute shell commands

• trigger CI/CD workflows

• access arbitrary repositories

• access arbitrary filesystem paths

• expose provider secrets

• modify repositories

Only explicitly configured sources are accessible.

Even when write support is enabled for local sources, writes remain constrained to the configured source root and continue to enforce:

• traversal protection

• blocklist enforcement

• binary detection

• path normalization

• UTF-8 text-only writes

Built-in Security Protections

Path Validation

The server rejects:

• parent traversal (../)

• absolute paths (/etc/passwd)

• double slashes (//)

• Windows backslashes (\)

• URL-encoded traversal attempts (%2e, %2f, %5c)

• null-byte injection attempts

Built-in Blocklist

The server always applies an internal protection layer.

Examples include:

• .git/

• .wrangler/

• node_modules/

• .env

• Terraform state files

• SSH folders

• certificates

• private keys

• generated artifacts

Blocklists are merged in this order:

DEFAULT_PATH_BLOCKLIST
→ defaults.pathBlocklist
→ source.pathBlocklist

Binary File Protection

The server refuses to read binary files using:

• extension-based filtering

• content-based binary detection

Filesystem Isolation

Local and network sources are constrained to their configured root path.

Example rejected request:

{
  "sourceKey": "local-api",
  "path": "../../.ssh/id_rsa"
}

Symlinks are disabled by default:

defaults:
  followSymlinks: false

Claude Desktop Setup

macOS Claude Desktop configuration path:

~/Library/Application Support/Claude/claude_desktop_config.json

Example:

{
  "mcpServers": {
    "sourceplane-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/sourceplane-mcp/dist/index.js"
      ],
      "env": {
        "SOURCEPLANE_CONFIG": "/absolute/path/to/sourceplane-mcp/config/sources.yaml",
        "GITHUB_TOKEN": "github_pat_xxx",
        "GITLAB_TOKEN": "glpat_xxx",
        "BITBUCKET_TOKEN": "xxx"
      }
    }
  }
}

Restart Claude Desktop after updating the configuration.

Automated Testing

Sourceplane MCP includes automated tests covering:

• traversal rejection

• nested blocklist enforcement

• filesystem isolation

• sanitized error handling

• binary detection

• provider URL construction

• GitLab provider behavior

• Bitbucket Cloud behavior

• Bitbucket Data Center behavior

• local source scanning

Current coverage includes:

• high coverage for security-critical logic

• mocked provider API tests

• CI validation on Node.js 20 and 22

Run tests:

npm run test
npm run coverage

Scripts

npm run dev
npm run build
npm run start
npm run clean
npm run test
npm run coverage

Design Principles

Sourceplane MCP favors:

• explicit configuration

• least privilege

• read-only-by-default access

• secure defaults

• predictable behavior

• local-first workflows

• self-hosted provider support

• easy auditing

It is intentionally narrower in scope than platform-automation MCP servers.

License

MIT License