{"slug": "build-a-custom-claude-mcp-server-for-your-local-codebase", "title": "Build a custom Claude MCP server for your local codebase", "summary": "A tutorial published on the Claude tag page details how to configure a local Model Context Protocol (MCP) filesystem server so Claude Desktop can read a project's files directly, requiring users to edit claude_desktop_config.json and add the @modelcontextprotocol/server-filesystem package via npx with an absolute project path. The guide notes the server's allowed-directories restriction blocks access outside the listed paths, requires Node 18 or higher, and takes 5-10 minutes to set up versus zero seconds for manual uploads, which the author says fill the context window instantly and go stale on save.", "body_md": "# Build a custom Claude MCP server for your local codebase\n\nForget the generic \"analyze my code\" prompts. To get [Claude](/en/tags/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.\n\nHere is the exact way to set up a local filesystem [MCP](/en/tags/mcp/) server so Claude can actually read your files and a way to manage the prompts you use to query them.\n\n## Get the MCP filesystem server running\n\nIf 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.\n\nOpen 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`.\n\nPaste 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.\n\n```\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/yourname/projects/my-app\"\n      ]\n    }\n  }\n}\n```\n\nRestart Claude Desktop completely. If you don't see a small hammer icon in the chat box, the server didn't load.\n\nThe 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.\n\n## Testing the connection with a real-world query\n\nDon't just ask \"can you see my files?\". That's too vague. Test it with a specific command that forces the tool to trigger.\n\nTry this:`list the files in the root directory and tell me which one is the entry point.`\n\nIf 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.\n\n## Stop rewriting your context prompts\n\nOnce 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.\n\nThis 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.\n\nHere is a template I use for refactoring specifically when using the filesystem MCP:\n\n**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.`\n\nWhen you scale this across a team, a shared [Workflows](/en/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.\n\n## Comparison of MCP vs. Manual File Uploads\n\nI tried both for a month on a 50k line project. Manual uploads are a nightmare for large repos.\n\n| Metric | Manual Upload (PDF/TXT) | MCP Filesystem Server |\n\n| :--- | :--- | :--- |\n\n| **Context Window** | Fills up instantly | Dynamic (reads only what it needs) |\n\n| **Freshness** | Stale the moment you save | Real-time local access |\n\n| **Setup Time** | 0 seconds | 5-10 minutes |\n\n| **Reliability** | High (files are there) | Medium (depends on path config) |\n\n| **Cost** | Higher (more input tokens) | Lower (precise reading) |\n\n## Why a community like PromptCube matters for this\n\nSetting 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.\n\nMost 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.\n\nJoining 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.\n\n## Common failure points to watch for\n\nIf the MCP server is acting up, it's usually one of three things:\n\n1. **Path issues**: Again, absolute paths only. `/Users/me/project`, not `./project`.\n\n2. **Npx caching**: Sometimes the `@modelcontextprotocol/server-filesystem` package updates and breaks. Run `npx clear-npx-cache` if things suddenly stop working.\n\n3. **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.\n\nGet the config right, build your template library, and you'll actually start shipping code instead of fighting with your tools.\n\n[Next ElevenLabs Music v2.5 is now out on the app and API →](/en/threads/9323/)\n\n[these AI tool field notes](https://tanyan888.com/), with plenty of directly applicable cases.", "url": "https://wpnews.pro/news/build-a-custom-claude-mcp-server-for-your-local-codebase", "canonical_source": "https://promptcube3.com/en/posts/9328/", "published_at": "2026-09-13 20:25:18+00:00", "updated_at": "2026-09-13 21:21:20.160448+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-products", "large-language-models"], "entities": ["Claude", "Claude Desktop", "Model Context Protocol", "@modelcontextprotocol/server-filesystem", "npx", "Node"], "alternates": {"html": "https://wpnews.pro/news/build-a-custom-claude-mcp-server-for-your-local-codebase", "markdown": "https://wpnews.pro/news/build-a-custom-claude-mcp-server-for-your-local-codebase.md", "text": "https://wpnews.pro/news/build-a-custom-claude-mcp-server-for-your-local-codebase.txt", "jsonld": "https://wpnews.pro/news/build-a-custom-claude-mcp-server-for-your-local-codebase.jsonld"}}