How do I use project-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@project-mcp search my-project for the authentication logic" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

project-mcp

by lduda79

Overview Schema Related Servers Score Discussions

Python

Local

project-mcp

A small, read-only MCP server that lets Claude read the source code of your projects. You keep your projects in one folder; Claude can then read the current version of your files instead of relying on pasted snippets.

The simple mental model

There is a projects/ folder.
You create one sub-folder per project inside it.
Claude can read the code in those sub-folders. That's it.

project-mcp/
  project_mcp.toml        <- one line of config
  projects/               <- you create this
    some-project/         <- project

Drop a new folder into projects/ and it shows up automatically — no config change needed.

Related MCP server: codebase-bridge-mcp

Setup

cd project-mcp
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .

mkdir projects                     # your projects live here
cp project_mcp.example.toml project_mcp.toml

The default project_mcp.toml needs a single line:

projects_root = "projects"

A relative path is resolved next to the config file, so this means "the projects/ folder next to this config". Done.

MCP version note: this server pins mcp>=1.2,<2. The official SDK is now at 2.0, which removed the from mcp.server.fastmcp import FastMCP import that this server (and research-mcp) use. The pin keeps it working and consistent with research-mcp.

Connect it to Claude Desktop

Add an entry to claude_desktop_config.json. Using the venv's Python by absolute path is the most robust:

{
  "mcpServers": {
    "project-mcp": {
      "command": "/absolute/path/to/project-mcp/.venv/bin/python",
      "args": ["-m", "project_mcp"],
      "env": {
        "PROJECT_MCP_CONFIG": "/absolute/path/to/project-mcp/project_mcp.toml"
      }
    }
  }
}

(On Windows use ...\.venv\Scripts\python.exe.) Restart Claude Desktop; project-mcp then appears next to research-mcp in the tool list. A good first check: ask Claude to run list_projects.

Tools (all read-only)

Tool	Purpose
`list_projects()`	the projects Claude can see + how many readable files each has
`list_files(project)`	readable files in a project (exclusions already applied)
`read_code(project, path, max_chars=100000)`	read one file
`search_code(query, project=None, max_results=50)`	substring search across readable files

No writing, no deleting — for "review my code" reading is enough and much safer.

Security model

The config is the policy, and it is enforced in code — the server cannot read anything the policy forbids, regardless of what a request says. Two boundaries are checked, in order:

The named project must be visible (either auto-discovered under projects_root, or on the include_projects allow-list if you set one).
The file must resolve to a path inside that project (containment is checked after Path.resolve(), so .. segments and symlinks are collapsed first and then rejected), must not sit in an excluded directory, must have an allowed suffix, and must not match an excluded glob (e.g. .env, *secret*).

By default any folder you place in projects/ is readable. If you want tighter control — say you keep NDA/company code around — set include_projects to an explicit allow-list so a project is only visible when you name it on purpose. Either way, the secret-file exclusions (.env, *.key, *secret*, …) always apply.

Tests

pytest      # 13 tests, focused on path confinement:
            # .. escapes, symlink escape, allow-list, exclusions, suffixes,
            # and auto-discovery

Project structure

project-mcp/
  project_mcp.example.toml   config template
  pyproject.toml
  src/project_mcp/
    config.py    load config (projects_root, optional allow-list, exclusions)
    safe_io.py   security core: safe_resolve + read / list / search
    server.py    FastMCP server + the four tools
  tests/test_safe_io.py

Available Tools

4 tools

list_filesA

Lists the readable source files inside one project.

Excluded directories (e.g. .git, .venv) and excluded patterns (e.g. secrets, .env files) are already filtered out - what you see here is exactly what read_code is allowed to open.

Args: project: A project name from list_projects, e.g. "conftransform".

ParametersJSON Schema

Name	Required	Description	Default
`project`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses that excluded directories and patterns are already filtered out, and that the list is exactly what read_code can open. This adds meaningful behavioral context beyond a simple 'list files' statement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief and front-loaded with the main purpose. Each subsequent sentence adds useful detail (exclusion behavior, parameter guidance) without fluff. The structured 'Args' block is clean and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool with one parameter and an output schema, the description covers purpose, key behavioral filtering, parameter sourcing, and relationship to sibling tools. No critical gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides no description (0% coverage), so the description compensates by explaining 'project' is a project name from list_projects, with an example. This gives the agent a clear origin and expected value format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Lists the readable source files inside one project' — a specific verb and resource. It also distinguishes itself from siblings by clarifying the list matches exactly what read_code is allowed to open, making its role clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context by explaining that the output corresponds to read_code's allowed files, implying when to use it (e.g., before read_code). It also references list_projects as the source of valid project names. However, it doesn't explicitly state when not to use it or compare to search_code.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_projectsA

Lists the projects you have made visible to project-mcp.

Each entry shows the project name, whether its folder currently exists, and how many readable source files it contains. Start here to see what is available before reading or searching.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and discloses useful behavioral details: it lists only visible projects, includes folder existence status, and counts readable source files. This goes beyond a bare 'list' and helps set expectations, though it omits edge cases like empty results or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the main purpose, followed by useful detail and usage guidance. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, has output schema) and the presence of an output schema, the description fully covers the essential aspects: what it lists, what state it reports, and when to use it. The sibling context further clarifies its role in the workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the schema is trivially complete. The description adds meaning by explaining what the returned entries contain, making it unnecessary to speculate about parameters. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource ('Lists the projects you have made visible to project-mcp') and differentiates from sibling tools like list_files and read_code by focusing on projects as a distinct entity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to 'Start here to see what is available before reading or searching,' which gives clear timing guidance and implicitly points to sibling tools (read_code, search_code) as later steps. Does not name alternatives explicitly, hence not a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_codeA

Reads the current content of one source file in a project.

Use this to see the up-to-date version of a file instead of relying on a pasted copy. Only files inside an allow-listed project, of an allowed type, and outside the excluded directories/patterns can be read.

Args: project: Project name, e.g. "conftransform". path: Project-relative path, e.g. "src/conftransform/levels.py". max_chars: Maximum number of characters to return.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`project`	Yes
`max_chars`	No

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses access restrictions (allow-listed project, allowed type, excluded directories) and implies truncation via max_chars, but does not detail error behavior for missing files or unauthorized paths. This is moderate coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a concise summary, usage guidance, constraints, and an Args list. Every sentence provides value without redundancy, making it easy to scan and understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema or annotations, the description covers the core aspects: what it does, when to use, constraints, and parameter meanings. It could explicitly mention the return value type (file content) and error handling, but the purpose is clear enough for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates with an Args section explaining project and path with concrete examples, and defines max_chars as 'Maximum number of characters to return.' This adds meaningful semantics beyond the schema's basic parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Reads the current content of one source file in a project,' using a specific verb and resource. It distinguishes itself from siblings like list_files (listing files) and search_code (searching within code) by focusing on direct file content retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage context: 'Use this to see the up-to-date version of a file instead of relying on a pasted copy.' It also describes constraints (allow-listed project, allowed type, excluded directories), but does not explicitly mention alternatives or when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_codeA

Searches for a plain-text substring across readable project files.

Case-insensitive. Returns matching locations as {project, path, line, text}. Use it to locate where something is defined or used without having to open files one by one.

Args: query: Text to look for, e.g. "SecurityLevel" or "def safe_resolve". project: Optional - restrict the search to a single project. max_results: Cap on the number of matches returned.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`project`	No
`max_results`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behavioral details: case-insensitivity, return format ({project, path, line, text}), and scope ('readable project files'). It also mentions max_results as a cap. Since no annotations are provided, this transparency is essential and adequately covers the main behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose, followed by a clear Args block. Each sentence serves a purpose without redundancy, making it easy to scan and understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, parameters, and behavior well, and the presence of an output schema reduces the need to explain return values. Minor omissions like handling of no matches or error cases are acceptable, but the description could be slightly more complete given no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant meaning to each parameter: query gets examples, project is described as restricting to a single project, and max_results is described as a cap. The schema only provides titles and defaults (0% description coverage), so this parameter documentation is vital and well-executed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Searches for a plain-text substring across readable project files.' It also provides concrete examples ('SecurityLevel', 'def safe_resolve') and distinguishes itself from siblings by focusing on search rather than listing or reading files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use it 'to locate where something is defined or used without having to open files one by one,' which gives clear context. However, it does not explicitly name alternatives or provide when-not-to-use conditions, so it stops short of full exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0

Disambiguation5/5

Each tool targets a distinct action and resource: listing projects, listing files, reading a file, and searching code. No overlap or ambiguity between them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: list_projects, list_files, read_code, search_code. The style is uniform and predictable.

Tool Count5/5

With 4 tools, the set is well-scoped for a read-only code exploration server. Each tool serves a necessary function and there is no bloat.

Completeness5/5

The toolset covers the full workflow of browsing projects: discover projects, list their files, read file contents, and search across them. No significant gaps for the intended domain.

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp
dev.augments
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Developer Tools Documentation Access
2128
gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5361
saagarpatel.dev Portfolio A
io.github.saagpatel
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Search Documentation Access
82
thoughts
ai.thoughtbox.api
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Cloud Storage Finance
2

Related MCP Servers

Claude Local Bridge
File Systems Security
suhteevah
A
license
Not graded
quality
D
maintenance
A secure MCP server that allows Claude to read and write local files on your machine with explicit approval gating for each access.
Updated 7 months ago (2026-02-16 08:22 UTC)
MIT
codebase-bridge-mcp
Code Analysis Developer Tools
EDMMY
A
license
A
quality
B
maintenance
A read-only MCP server that lets a Claude chat explore your local repository and answer questions about it, returning synthesized answers with file:line references.
Updated 2 months ago (2026-06-27 05:01 UTC)
3
1
MIT
mcp-readonly-code-server
John0615
F
license
B
quality
C
maintenance
A read-only MCP server that exposes a local code workspace to AI clients via stdio, providing file browsing and text search capabilities with path safety rules.
Updated 2 months ago (2026-07-18 08:30 UTC)
1
throughline
Code Analysis Developer Tools Search
devznsh
A
license
Not graded
quality
B
maintenance
An MCP server that indexes local code repositories, extracting symbols and call graphs to give Claude precise, structural answers with real file paths and line numbers. Runs entirely locally with no network requests, for privacy-focused code understanding.
Updated a month ago (2026-08-02 19:07 UTC)
646
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lduda79/projects-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server