Build an MCP Server for the Code Journals App:

  • In Unit 2 you built an MCP server that turned a couple of Python functions into tools Claude Desktop could call.
  • Now we’ll use that same pattern with our Code Journals application and have Claude Desktop query and summarize our database for us.
    • We will write a server with one tool that lists every journal topic and counts how many entries each topic has.

Install FastMCP:

On Windows:

1pip install fastmcp

On Mac (use pip3, not pip):

1pip3 install fastmcp

Create the mcp_server.py File:

  • In VS Code, create a new file named mcp_server.py in your activity root folder (the same folder as manage.py).
  • Copy and paste each code block below into mcp_server.py, in order, one after the other.

Step 1: Connect the Server to Django:

mcp_server.py

python
1import django, os
2from fastmcp import FastMCP
3
4# Tell Django where the project settings are, then start Django
5os.environ.setdefault("DJANGO_SETTINGS_MODULE", "code_journal.settings")
6django.setup()
7
8# Import the Topic class
9from code_journals.models import Topic 
  • This is the same setup you used in populate_entries.py. Since we are running our own script instead of manage.py, we have to start Django ourselves.
    • DJANGO_SETTINGS_MODULE tells Django to use the settings.py file inside the code_journal folder.
    • django.setup() loads the project so we can work with the database.
  • On line 9, we import the Topic model. We have to wait until after django.setup() runs to import it, otherwise Django isn’t ready yet.

Step 2: Create the MCP Server:

mcp_server.py

python
11# Create a FastMCP instance
12mcp = FastMCP("CodeJournal")
  • On line 12, we create an instance of FastMCP and name our server “CodeJournal”. This is our server.

Step 3: Define the Tool:

mcp_server.py

python
14# Define a tool to count entries by topic
15@mcp.tool()
16def count_entries_by_topic() -> list:
17    """Return each journal topic with the number of entries it has."""
18    topics = Topic.objects.all()
19    return [{"topic": topic.text, "entries": topic.entry_set.count()} for topic in topics]
  • On line 15, the @mcp.tool() decorator registers the function below it as something Claude is allowed to call.
  • On line 16, the function takes no parameters, since Claude doesn’t need to give it anything. The -> list type hint tells Claude it will get a list back.
  • On line 17, the docstring tells Claude what the tool does, so it knows when to use it.
  • On line 18, Topic.objects.all() gets every topic from the database, just like in the Django shell.
  • On line 19, a list comprehension builds a list of dictionaries, one dictionary per topic:
    • topic.text is the name of the topic (ex. Data_Types).
    • topic.entry_set gives us all the entries connected to that topic through the foreign key. Django creates entry_set for us automatically, because the Entry model has a foreign key to Topic.
    • .count() asks the database how many of those entries there are.
  • The result Claude receives will look something like this:
[{"topic": "Data_Types", "entries": 5}, {"topic": "Lists", "entries": 5}]

Step 4: Run the Server:

mcp_server.py

python
21if __name__ == "__main__":
22    mcp.run()
  • On line 22, mcp.run() starts the server and waits for Claude Desktop to call our tool.
  • You don’t run this file yourself. Claude Desktop starts it for you in the background, as long as the configuration file (next section) tells it where to find the file.

Find Your Two Paths:

  • Claude Desktop needs two full (absolute) paths: where Python is installed, and where mcp_server.py is saved.
  • From the folder that has manage.py, run these commands in the VS Code terminal and copy each result somewhere handy:

On Windows:

1python -c "import sys; print(sys.executable)"
2pwd

On Mac:

1python3 -c "import sys; print(sys.executable)"
2pwd
  • The first command prints the path to Python (ex. C:\Users\jsmith\AppData\Local\Programs\Python\Python314\python.exe or /Library/Frameworks/Python.framework/Versions/3.14/bin/python3).
  • The second command prints the path to your activity folder. Add /mcp_server.py to the end of it to get the full path to your server file.

Update the claude_desktop_config.json File:

  • Edited on 11/2 at 11:30 AM: Open Claude Desktop and go to Settings → Desktop App → Extensions → Edit Config. This opens the folder that holds claude_desktop_config.json. Open that file in VS Code.

  • Add a “code-journal” entry inside “mcpServers”. If you still have “course-tools” from Unit 2, put a comma after its closing } and add the new entry below it. If the file has other settings (like “preferences”), leave them alone.

On Windows:

json
1{
2  "mcpServers": {
3    "code-journal": {
4      "command": "C:\\Users\\jsmith\\AppData\\Local\\Programs\\Python\\Python314\\python.exe",
5      "args": ["C:\\Users\\jsmith\\Desktop\\Activity6-IndividualPages\\mcp_server.py"]
6    }
7  }
8}

On Mac:

json
1{
2  "mcpServers": {
3    "code-journal": {
4      "command": "/Library/Frameworks/Python.framework/Versions/3.14/bin/python3",
5      "args": ["/Users/jsmith/Desktop/Activity6-IndividualPages/mcp_server.py"]
6    }
7  }
8}
  • Replace both paths with your own paths from the previous section.
    • “command” is the path to Python.
    • “args” is the path to mcp_server.py.
  • Windows users: every backslash in your paths must be typed twice as shown above because JSON uses backslashes as escape characters. (Forward slashes / also work, if you prefer.)
  • Save the file.
  • Completely quit and reopen Claude Desktop so it picks up the change.
  • Open Settings → Connectors in Claude Desktop. You should see code-journal listed. Make sure it’s enabled.

Test the Tool:

  • Start a new conversation in Claude Desktop and ask it something that requires your tool, for example:
1Please list my Code Journal topics and tell me how many entires I have recorded.
  • Claude will call your tool, which queries db.sqlite3, and then use the list it gets back to answer in plain English.