Build an MCP Server in Python: A Notes Search Server, Step by Step

How to build an MCP server in Python, step by step

1. Step 1. Set up the project

   Create a project with uv and add the SDK with its CLI extra. The cli extra installs the mcp command used for testing and installing.

   uv init notes-mcp
   cd notes-mcp
   uv add "mcp[cli]"
   mkdir notes

   Using pip instead? Create and activate a virtual environment, then run pip install "mcp[cli]". Put a few .md or .txt files in the notes folder: lecture notes, a to-do list, interview prep. Small files are perfect for a first test.

2. Step 2. Create the server and your first tool

   Create server.py. The MCPServer object is your server, and each function decorated with @mcp.tool() becomes a tool. The type hints become the input schema and the docstring becomes the description the model reads.

   # server.py
   from pathlib import Path
   from mcp.server import MCPServer
   from mcp.server.mcpserver.exceptions import ToolError
   
   mcp = MCPServer("Notes")
   NOTES = Path(__file__).resolve().parent / "notes"  # absolute, so any host finds it
   
   def note_files():
       return sorted(p for p in NOTES.iterdir() if p.suffix in {".md", ".txt"})
   
   @mcp.tool()
   def list_notes() -> list[str]:
       """List the file names of all notes (.md and .txt)."""
       return [p.name for p in note_files()]

   The NOTES path is built from the file's own location, not the current folder. Hosts launch servers from their own working directory, so a relative path like "notes" would point somewhere unexpected.

3. Step 3. Add search and read tools

   Add two more tools below the first. search_notes finds matching lines across every note; read_note returns one whole file but refuses anything outside the notes folder.

   @mcp.tool()
   def search_notes(query: str, max_results: int = 10) -> list[str]:
       """Find lines in the notes that contain the query (case-insensitive)."""
       hits = []
       for p in note_files():
           for no, line in enumerate(p.read_text(encoding="utf-8").splitlines(), 1):
               if query.lower() in line.lower():
                   hits.append(f"{p.name}:{no}: {line.strip()}")
       return hits[:max_results] or ["No matches."]
   
   @mcp.tool()
   def read_note(name: str) -> str:
       """Return the full text of one note, e.g. dbms.md."""
       path = (NOTES / name).resolve()
       if path.parent != NOTES or not path.is_file():
           raise ToolError(f"No note called {name!r}. Call list_notes first.")
       return path.read_text(encoding="utf-8")[:8000]
   
   if __name__ == "__main__":
       mcp.run()  # stdio by default: the host talks to it over stdin/stdout

   Raising ToolError sends a clear error message back to the model instead of crashing, so the model can recover by calling list_notes. The path check blocks requests such as ../../secrets.txt.

4. Step 4. Test it in the MCP Inspector

   The MCP Inspector is the official browser-based tester for MCP servers. Start your server inside it with one command:

   uv run mcp dev server.py

   Open the URL it prints, connect, and go to the Tools tab. You should see list_notes, search_notes and read_note, each with a form built from your type hints. Call search_notes with a word from your notes, then try read_note with a file that does not exist to see your ToolError message.

   The Inspector runs on Node.js, so mcp dev needs npx on your PATH. Its README lists the minimum Node version (22.19 or newer at the time of writing). You can also start the Inspector directly with npx @modelcontextprotocol/inspector and point it at your server's launch command.

5. Step 5. Write a quick automated test

   The SDK's Client can connect to your server object in memory, with no subprocess or port, which makes testing fast.

   # test_client.py
   import anyio
   from mcp import Client
   from server import mcp
   
   async def main():
       async with Client(mcp) as client:
           tools = await client.list_tools()
           print([t.name for t in tools.tools])
           result = await client.call_tool("search_notes", {"query": "exam"})
           print(result.structured_content)
           bad = await client.call_tool("read_note", {"name": "../secrets.txt"})
           print(bad.is_error, bad.content[0].text)
   
   anyio.run(main)

   Run it with uv run test_client.py. You should see the three tool names, a dictionary whose result key holds the matching lines, and True followed by your error message for the blocked path. A test you can rerun after every change is what separates a project from a demo.

6. Step 6. Connect the server to Claude Desktop

   The quickest way is the SDK's install command, which writes the config entry for you with absolute paths:

   uv run mcp install server.py

   To do it by hand, open claude_desktop_config.json. On macOS it lives at ~/Library/Application Support/Claude/claude_desktop_config.json and on Windows at %APPDATA%\Claude\claude_desktop_config.json. Add your server under the mcpServers key:

   {
     "mcpServers": {
       "notes": {
         "command": "uv",
         "args": ["--directory", "C:/Users/you/notes-mcp", "run", "server.py"]
       }
     }
   }

   Use the absolute path to your project folder. If Claude Desktop cannot find uv, put the full path to the uv executable in command (find it with where uv on Windows or which uv on macOS). Then fully quit Claude Desktop, not just its window, and reopen it.

7. Step 7. Try it with real questions

   Ask Claude Desktop questions that need your tools:

   • "List my notes."
   • "Search my notes for normalisation and explain what I wrote."
   • "Read dbms.md and make five quiz questions from it."

   The host asks your permission before it runs a tool, and you can see which tool it called with which arguments. Note how the model chains tools on its own: it may call search_notes first, then read_note on the best match. If it picks the wrong tool, improve that tool's docstring, restart the host and try again.

Frequently asked questions

Keep learning

References

• Model Context Protocol: Build an MCP server
• MCP Python SDK documentation (v2)
• MCP Python SDK: connect to a real host
• MCP Python SDK on GitHub
• MCP Inspector on GitHub