Build a custom Claude MCP server for your local codebase

Forget the generic "analyze my code" prompts. To get Claude to actually understand your project structure without hallucinating paths, you need a Model Context Protocol (MCP) server that bridges the gap between the LLM and your local file system. I spent four hours last Thursday fighting with path permissions and node_modules recursion before I realized I was just configuring the mcp-server-filesystem incorrectly.

Here is the exact way to set up a local filesystem MCP server so Claude can actually read your files and a way to manage the prompts you use to query them.

Get the MCP filesystem server running #

If you are using Claude Desktop, you don't "install" MCP servers via a GUI. You edit a JSON config file. This is where most people trip up—one missing comma and Claude just ignores the server entirely.

Open your claude_desktop_config.json. On macOS, it's at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, check %APPDATA%\Claude\claude_desktop_config.json.

Paste this configuration. Replace /Users/yourname/projects/my-app with the actual absolute path to your project. Do not use ~ or relative paths; they will fail.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects/my-app"
      ]
    }
  }
}

Restart Claude Desktop completely. If you don't see a small hammer icon in the chat box, the server didn't load.

The biggest pain point here is the "allowed directories" restriction. The filesystem server is locked down for security. If you try to access a file outside the directory listed in the args array, Claude will tell you it can't find the file, even if it's right there. If you have a monorepo, add every top-level directory explicitly in that list.

Testing the connection with a real-world query #

Don't just ask "can you see my files?". That's too vague. Test it with a specific command that forces the tool to trigger.

Try this:list the files in the root directory and tell me which one is the entry point.

If it works, you'll see a "Tool Use" block in the UI where Claude calls list_directory. If it fails, check your terminal for npx errors. I once spent an hour debugging this only to find out my node version was 14 and the server needed 18+. Use node -v to verify.

Stop rewriting your context prompts #

Once the MCP server is live, you'll find yourself typing the same setup instructions every time you start a new session. "Read the package.json, look at the src/types folder, and then suggest a change." This is a waste of tokens and time.

This is why I started building a prompt template library. Instead of relying on memory, I keep a markdown file of "Context Blueprints" that I can copy-paste or trigger via a snippet manager.

Here is a template I use for refactoring specifically when using the filesystem MCP:

Refactor Blueprint:Use the filesystem tool to read [FILE_A] and [FILE_B]. Analyze the dependency between them. I want to move the logic in [FILE_A] to a new utility class. Suggest the file structure changes first, then provide the code.

When you scale this across a team, a shared Workflows document becomes the source of truth. If everyone uses the same prompt templates to query the MCP server, the AI's output becomes predictable and consistent across different developers' machines.

Comparison of MCP vs. Manual File Uploads #

I tried both for a month on a 50k line project. Manual uploads are a nightmare for large repos.

| Metric | Manual Upload (PDF/TXT) | MCP Filesystem Server |

| :--- | :--- | :--- |

| Context Window | Fills up instantly | Dynamic (reads only what it needs) |

| Freshness | Stale the moment you save | Real-time local access |

| Setup Time | 0 seconds | 5-10 minutes |

| Reliability | High (files are there) | Medium (depends on path config) |

| Cost | Higher (more input tokens) | Lower (precise reading) |

Why a community like PromptCube matters for this #

Setting up the JSON file is the easy part. The hard part is knowing which MCP servers actually work and which prompts trigger the most accurate file reads.

Most developers are just guessing. When you join a community like PromptCube, you stop guessing. You get access to shared prompt template libraries that have been battle-tested on massive codebases. It's the difference between spending an afternoon tweaking a prompt and just importing a "Production-Ready Refactor" template that actually works.

Joining means you get a place to store these templates outside of a messy .txt file on your desktop and a way to collaborate on the specific logic required to make LLMs handle complex directory structures without getting lost.

Common failure points to watch for #

If the MCP server is acting up, it's usually one of three things:

1. Path issues: Again, absolute paths only. /Users/me/project, not ./project.

2. Npx caching: Sometimes the @modelcontextprotocol/server-filesystem package updates and breaks. Run npx clear-npx-cache if things suddenly stop working.

3. Permission prompts: On macOS, you might get a popup asking if Claude can access your Files and Folders. If you ignore it or click "Deny", the server will start but every read_file call will return an empty string or an error.

Get the config right, build your template library, and you'll actually start shipping code instead of fighting with your tools.

Next ElevenLabs Music v2.5 is now out on the app and API →

these AI tool field notes, with plenty of directly applicable cases.