mcp server

sourceplane-mcp

Secure multi-source MCP server for local repositories, GitHub, GitLab, and Bitbucket

infraws/sourceplane-mcpcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

Node.js 20 or newer

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

{
  "mcpServers": {
    "sourceplane-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "sourceplane-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 21, 2026

Sourceplane MCP

License

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

Source Type	Description	Token Required
`github`	GitHub repository via API	Optional for public repos
`gitlab`	GitLab project via API	Optional for public projects
`bitbucket`	Bitbucket Cloud or Data Center repository	Optional for public repos
`local`	Local workspace folder	No
`network`	Mounted NAS or network share	No

Network sources are mounted filesystem paths such as:

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

They are not arbitrary internet URLs.

Current Capability Matrix

Capability	GitHub	GitLab	Bitbucket Cloud	Bitbucket Data Center	Local	Network
Public source without token	Yes	Yes	Yes	Usually internal only	N/A	N/A
Private source with token	Yes	Yes	Yes	Yes	N/A	N/A
Custom `host`	Yes	Yes	Yes	Yes	N/A	N/A
Custom `webUrl`	Yes	Yes	Yes	Yes	N/A	N/A
`list_sources`	Yes	Yes	Yes	Yes	Yes	Yes
`read_file`	Yes	Yes	Yes	Yes	Yes	Yes
`read_files`	Yes	Yes	Yes	Yes	Yes	Yes
`list_files`	Yes	Yes	Yes	Yes	Yes	Yes
`get_source_structure`	Yes	Yes	Yes	Yes	Yes	Yes
`search_code`	API search	API search / tree search	Tree-based search	Tree-based search	Local scan	Local scan
Branch override	Yes	Yes	Yes	Yes	No	No
Built-in blocklist	Yes	Yes	Yes	Yes	Yes	Yes
Source-specific blocklist	Yes	Yes	Yes	Yes	Yes	Yes
Write operations	No	No	No	No	Optional local-only	No

Available MCP Tools

Tool	Description
`list_sources`	List configured sources
`read_file`	Read a single file
`read_files`	Read multiple files
`list_files`	List files in a directory
`get_source_structure`	Get recursive source tree
`search_code`	Search source code
`write_file`	Write a UTF-8 text file to an explicitly writable local source

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

sourceplane-mcp

Set up

README

Sourceplane MCP

Why Sourceplane MCP Exists

Supported Sources

Current Capability Matrix

Available MCP Tools

Installation

Requirements

Clone Repository

Install Dependencies

Build

Configuration

Example Configuration

Local Development Write Support

Example Writable Local Source

Example write_file

Security Model

Built-in Security Protections

Path Validation

Built-in Blocklist

Binary File Protection

Filesystem Isolation

Claude Desktop Setup

Automated Testing

Scripts

Design Principles

License

Example `write_file`